@soulcraft/cor 3.0.17 → 3.0.18

package/dist/utils/NativeMetadataIndex.d.ts

@@ -133,6 +133,21 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      * init() (`columnStore.init` / `warmCache` / `lazyLoadCounts`) on shared state.
      */
     private epochMigrationPending;
+    /**
+     * TRUE when {@link wireIdMapper}'s factory CREATED the mmap mapper fresh
+     * this open (both `_id_mapper/*` stores were absent). Benign on a truly
+     * fresh brain; POISON when durable int-keyed postings survive alongside
+     * it (a lost/deleted `_id_mapper/` directory) — every surviving posting
+     * references ints the new mapper never assigned, and minting would pair
+     * NEW ints against OLD-int postings silently. Detected right after the
+     * LSM cold-open; the response is the coordinated full rebuild.
+     */
+    private idMapperCreatedFresh;
+    /** TRUE when the lost-mapper guard fired this open: the coordinated
+     * rebuild must complete BEFORE init returns (blocking), because until
+     * vector+graph re-mint, their durable state pairs old ints with a
+     * mapper that never assigned them — strictly unservable. */
+    private lostMapperHeal;
     private lastFlushTime;
     private autoFlushThreshold;
     private dirtyFields;

package/dist/utils/NativeMetadataIndex.js

@@ -35,6 +35,7 @@ const BUCKETED_INDEX_FIELDS = new Set([
 import { TypeUtils, NOUN_TYPE_COUNT, VERB_TYPE_COUNT } from '@soulcraft/brainy/types/graphTypes';
 import { loadNativeModule } from '../native/index.js';
 import { composeInvariantReport } from './invariantReport.js';
+import { opsLine } from './opsLog.js';
 import { declareDerivedFamilies, METADATA_FAMILIES } from './derivedFamilies.js';
 import { openOrCreateBinaryIdMapper } from './binaryIdMapperFactory.js';
 import { NativeColumnStore } from './NativeColumnStore.js';
@@ -222,6 +223,21 @@ export class MetadataIndexManager {
      * init() (`columnStore.init` / `warmCache` / `lazyLoadCounts`) on shared state.
      */
     epochMigrationPending = false;
+    /**
+     * TRUE when {@link wireIdMapper}'s factory CREATED the mmap mapper fresh
+     * this open (both `_id_mapper/*` stores were absent). Benign on a truly
+     * fresh brain; POISON when durable int-keyed postings survive alongside
+     * it (a lost/deleted `_id_mapper/` directory) — every surviving posting
+     * references ints the new mapper never assigned, and minting would pair
+     * NEW ints against OLD-int postings silently. Detected right after the
+     * LSM cold-open; the response is the coordinated full rebuild.
+     */
+    idMapperCreatedFresh = false;
+    /** TRUE when the lost-mapper guard fired this open: the coordinated
+     * rebuild must complete BEFORE init returns (blocking), because until
+     * vector+graph re-mint, their durable state pairs old ints with a
+     * mapper that never assigned them — strictly unservable. */
+    lostMapperHeal = false;
     lastFlushTime = Date.now();
     autoFlushThreshold = 10;
     dirtyFields = new Set();
@@ -1123,6 +1139,36 @@ export class MetadataIndexManager {
         // with NO O(N) rebuild. Runs after wireIdMapper (the engine's posting
         // lists reference the mapper's entity ints) and before any read/mutation.
         await this.openLsmEngine();
+        // LOST-MAPPER GUARD (MEMORY-COR-IDMAP-MIGRATION, root-caused
+        // 2026-07-14): the ONE genuinely dangerous open-state — the mmap
+        // mapper was just created EMPTY while durable int-keyed postings
+        // survive. (Empirically: 3.0.x-born brains carry their mapper and
+        // upgrade cleanly; this cell arises from a lost/deleted `_id_mapper/`
+        // directory, e.g. deleter-era damage.) Serving would resolve every
+        // surviving posting through ints the mapper never assigned, and the
+        // 3.0.16 mint would pair NEW ints against OLD-int postings silently.
+        // Response: loud, then the coordinated full rebuild (metadata →
+        // vector → graph under the migration lock) so re-minted ints are
+        // globally consistent; strandDetected is the belt when no
+        // coordinator is wired (raw/test usage) so the metadata leg at least
+        // reports not-ready instead of serving wrong pairings.
+        // The trigger is EMPTINESS, not who-created-it: TWO entry points open
+        // `_id_mapper/*` (this manager and the plugin's entityIdMapper
+        // provider), and whichever runs first re-creates the directories — a
+        // created-fresh flag from one path is blind to the other. An EMPTY
+        // mapper alongside durable postings is the poison regardless of how
+        // it got empty (deleted directory, truncated store).
+        const mapperEmpty = this.native.entityIdMapperSize() === 0;
+        if ((this.idMapperCreatedFresh || mapperEmpty) && this.lsmHasDurableState()) {
+            opsLine(`LOST-MAPPER: _id_mapper/ was recreated EMPTY while durable ` +
+                `int-keyed postings survive — the surviving index state is ` +
+                `unresolvable and would serve WRONG pairings. Forcing the ` +
+                `coordinated full rebuild from canonical (metadata + vector + ` +
+                `graph; ints re-mint consistently).`);
+            this.strandDetected = true;
+            this.epochMigrationPending = true;
+            this.lostMapperHeal = true;
+        }
         // **#18 read-side epoch guard.** AFTER the cortex-2.x legacy gate and the
         // LSM cold-open, classify the brain's derived-index epoch against this
         // build's expectation. The common case (current epoch) is a single tiny
@@ -1158,6 +1204,13 @@ export class MetadataIndexManager {
                         prodLog.info('[NativeMetadataIndex] Field registry missing but the LSM engine ' +
                             'recovered durable state (SSTables/memtable) — serving from it, ' +
                             'NO rebuild.');
+                        // DETECTOR COVERAGE (memory-vm 2026-07-14): this early serve
+                        // path previously SKIPPED detectDerivedStrand entirely — a
+                        // brain with lost postings that also lost its field registry
+                        // served the gap SILENTLY (posted < canonical, zero log
+                        // lines). The strand check is boot-path-invariant: it runs
+                        // here too, with the same verified-unpostable allowance.
+                        await this.detectDerivedStrand();
                         this.readinessInitialized = true;
                         return;
                     }
@@ -1235,7 +1288,24 @@ export class MetadataIndexManager {
         this.readinessInitialized = true;
         if (this.epochMigrationPending) {
             this.epochMigrationPending = false;
-            this.migrationCoordinatorGetter?.()?.start().catch(() => { });
+            const coordinator = this.migrationCoordinatorGetter?.();
+            if (this.lostMapperHeal) {
+                // Lost-mapper heal BLOCKS init: until vector+graph re-mint, their
+                // durable state pairs old ints with a mapper that never assigned
+                // them — brainy must not get an initialized brain before the
+                // coordinated rebuild completes. (The epoch path below stays
+                // fire-and-forget per the rc.9 lock contract — brainy sees the
+                // stale marker and waits on the lock itself.)
+                this.lostMapperHeal = false;
+                if (coordinator) {
+                    await coordinator.start();
+                }
+                // No coordinator (raw/test usage): strandDetected already gates
+                // the metadata leg; the loud LOST-MAPPER ops line stands.
+            }
+            else {
+                coordinator?.start().catch(() => { });
+            }
         }
     }
     /**
@@ -1435,9 +1505,9 @@ export class MetadataIndexManager {
                             `so the cold-open gate rebuilds from canonical.`);
                     }
                     else if (unpostable > 0 && posted < canonical) {
-                        prodLog.info(`[NativeMetadataIndex] posted ${posted} < canonical ${canonical} is ` +
-                            `FULLY explained by ${unpostable} verified metadata-less canonical ` +
-                            `entities (stamped by the last completed rebuild) — no strand, no heal.`);
+                        opsLine(`posted ${posted} < canonical ${canonical} is FULLY explained by ` +
+                            `${unpostable} verified metadata-less canonical entities (stamped ` +
+                            `by the last completed rebuild) — no strand, no heal.`);
                     }
                 }
             }
@@ -1468,6 +1538,7 @@ export class MetadataIndexManager {
             idSpace: 'u64',
         });
         this.idMapperNative = handle.mapper;
+        this.idMapperCreatedFresh = handle.created;
         this.native.setIdMapper(handle.mapper);
     }
     async loadFieldRegistry() {
@@ -3008,7 +3079,7 @@ export class MetadataIndexManager {
                 verbCount: verbResult.noMetadata,
                 verifiedAt: Date.now(),
             });
-            prodLog.info(`Metadata index rebuild completed! Processed ${nounResult.processed} nouns and ` +
+            opsLine(`Metadata index rebuild completed! Processed ${nounResult.processed} nouns and ` +
                 `${verbResult.processed} verbs` +
                 (nounResult.noMetadata > 0
                     ? ` (${nounResult.noMetadata} canonical noun(s) verified metadata-less — stamped for the strand detector)`
@@ -3081,8 +3152,8 @@ export class MetadataIndexManager {
                     if (processed - lastProgressAt >= 500) {
                         lastProgressAt = processed;
                         const elapsedS = (Date.now() - startedAt) / 1000;
-                        prodLog.info(`[NativeMetadataIndex] rebuild(${kind}): ${processed} posted ` +
-                            `in ${elapsedS.toFixed(1)}s (${(processed / Math.max(elapsedS, 0.001)).toFixed(0)}/s)`);
+                        opsLine(`rebuild(${kind}): ${processed} posted in ${elapsedS.toFixed(1)}s ` +
+                            `(${(processed / Math.max(elapsedS, 0.001)).toFixed(0)}/s)`);
                     }
                     if (++sinceFlush >= 5000) {
                         await this.flushRebuildDirty();
@@ -3099,11 +3170,11 @@ export class MetadataIndexManager {
             await this.yieldToEventLoop();
         }
         const totalS = (Date.now() - startedAt) / 1000;
-        prodLog.info(`[NativeMetadataIndex] rebuild(${kind}): COMPLETE — ${processed} posted ` +
+        opsLine(`rebuild(${kind}): COMPLETE — ${processed} posted ` +
             `in ${totalS.toFixed(1)}s (${(processed / Math.max(totalS, 0.001)).toFixed(0)}/s)` +
             (noMetadata > 0 ? `, ${noMetadata} without metadata` : ''));
         if (noMetadata > 0) {
-            prodLog.warn(`[NativeMetadataIndex] rebuild(${kind}): ${noMetadata} enumerated ` +
+            opsLine(`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. First ids: ` +

package/dist/utils/opsLog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module utils/opsLog
+ * @description The always-visible operational channel (CORTEX-RESTART-STRAND,
+ * 2026-07-14). brainy's prodLog defaults to ERROR level in production, which
+ * silenced ALL heal narration on memory-vm — an operator could not tell a
+ * converging heal from a hang until BRAINY_LOG_LEVEL=info was set by hand.
+ * Index lifecycle events (heal start / progress / completion, verified
+ * anomaly accounting) are OPERATIONAL, not debug: they must reach the
+ * journal regardless of logger configuration, exactly like the version
+ * banner. One writer, `console.error`, `[cor]`-prefixed — never routed
+ * through prodLog (no duplicate lines on boxes that set info-level).
+ */
+/** Emit one always-visible operational line. */
+export declare function opsLine(message: string): void;
+//# sourceMappingURL=opsLog.d.ts.map

package/dist/utils/opsLog.js

@@ -0,0 +1,17 @@
+/**
+ * @module utils/opsLog
+ * @description The always-visible operational channel (CORTEX-RESTART-STRAND,
+ * 2026-07-14). brainy's prodLog defaults to ERROR level in production, which
+ * silenced ALL heal narration on memory-vm — an operator could not tell a
+ * converging heal from a hang until BRAINY_LOG_LEVEL=info was set by hand.
+ * Index lifecycle events (heal start / progress / completion, verified
+ * anomaly accounting) are OPERATIONAL, not debug: they must reach the
+ * journal regardless of logger configuration, exactly like the version
+ * banner. One writer, `console.error`, `[cor]`-prefixed — never routed
+ * through prodLog (no duplicate lines on boxes that set info-level).
+ */
+/** Emit one always-visible operational line. */
+export function opsLine(message) {
+    console.error(`[cor] ${message}`);
+}
+//# sourceMappingURL=opsLog.js.map

package/dist/version.d.ts

@@ -11,5 +11,5 @@
  * `check:brainy`-style drift between the two fails the release.
  */
 /** The @soulcraft/cor version this build was cut from. */
-export declare const COR_VERSION = "3.0.17";
+export declare const COR_VERSION = "3.0.18";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -11,5 +11,5 @@
  * `check:brainy`-style drift between the two fails the release.
  */
 /** The @soulcraft/cor version this build was cut from. */
-export const COR_VERSION = '3.0.17';
+export const COR_VERSION = '3.0.18';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.17",
+  "version": "3.0.18",
   "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",