@soulcraft/cor 3.0.16 → 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;
@@ -563,6 +578,16 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      *    same rebuild). Skipped at/above the u32 saturation point of
      *    `getTotalEntityCount` (a saturated count would make equality lie).
      */
+    /**
+     * The verified-unpostable allowance for posted-vs-canonical floors: how
+     * many canonical noun rows the last COMPLETED rebuild PROVED carry no
+     * readable metadata (each verified by direct read at rebuild time, each
+     * RE-VERIFIED here so an id that has since gained metadata stops
+     * counting). Beyond {@link UNPOSTABLE_ID_CAP} the stamp is count-only
+     * and the allowance carries a bounded, logged staleness caveat.
+     * Advisory: any fault reads as 0 (may over-heal, never under-detects).
+     */
+    private verifiedUnpostableAllowance;
     private detectDerivedStrand;
     /**
      * **#72 Phase C.** Build the shared mmap `BinaryIdMapper` from the

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';
@@ -73,6 +74,20 @@ const LSM_MANIFEST_VERSION = 2;
  * field registry already depends on.
  */
 const LSM_MANIFEST_KEY = '__metadata_lsm_manifest__';
+/**
+ * Durable stamp of the entities a COMPLETED rebuild verified as
+ * unpostable (canonical rows with NO readable metadata — verified by
+ * direct read, not invented postings). The strand detector's
+ * posted-count floor accounts for them: without this, a fixed cohort of
+ * metadata-less canonical rows makes EVERY boot read as stranded and
+ * re-triggers a pointless full heal forever (memory-vm's constant-52,
+ * CORTEX-RESTART-STRAND 2026-07-13 — four consecutive boots).
+ */
+const UNPOSTABLE_STAMP_KEY = '__metadata_verified_unpostable__';
+/** Above this many ids the stamp stores count-only (the boot-time
+ * re-verify would stop being cheap); detection then carries a bounded
+ * staleness caveat, logged when it engages. */
+const UNPOSTABLE_ID_CAP = 1000;
 /**
  * **LSM durability (step 5).** Lower clamp (32 MiB) for the bounded-memtable
  * size-flush trigger. Even when the dynamic 'metadata' budget is tiny, the
@@ -208,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();
@@ -1109,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
@@ -1144,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;
                     }
@@ -1221,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(() => { });
+            }
         }
     }
     /**
@@ -1275,6 +1359,41 @@ export class MetadataIndexManager {
      *    same rebuild). Skipped at/above the u32 saturation point of
      *    `getTotalEntityCount` (a saturated count would make equality lie).
      */
+    /**
+     * The verified-unpostable allowance for posted-vs-canonical floors: how
+     * many canonical noun rows the last COMPLETED rebuild PROVED carry no
+     * readable metadata (each verified by direct read at rebuild time, each
+     * RE-VERIFIED here so an id that has since gained metadata stops
+     * counting). Beyond {@link UNPOSTABLE_ID_CAP} the stamp is count-only
+     * and the allowance carries a bounded, logged staleness caveat.
+     * Advisory: any fault reads as 0 (may over-heal, never under-detects).
+     */
+    async verifiedUnpostableAllowance() {
+        try {
+            const stamp = (await this.storage.getMetadata(UNPOSTABLE_STAMP_KEY));
+            if (!stamp || typeof stamp.nounCount !== 'number' || stamp.nounCount <= 0)
+                return 0;
+            if (Array.isArray(stamp.nounIds) && stamp.nounIds.length === stamp.nounCount) {
+                const getMeta = this.storage.getNounMetadata;
+                if (typeof getMeta !== 'function')
+                    return stamp.nounCount;
+                let stillUnpostable = 0;
+                for (const id of stamp.nounIds) {
+                    const md = await getMeta.call(this.storage, id).catch(() => undefined);
+                    if (md == null)
+                        stillUnpostable++;
+                }
+                return stillUnpostable;
+            }
+            prodLog.warn(`[NativeMetadataIndex] unpostable stamp is count-only ` +
+                `(${stamp.nounCount} > id cap) — the posted-count floor carries its ` +
+                `staleness until the next completed rebuild refreshes it.`);
+            return stamp.nounCount;
+        }
+        catch {
+            return 0;
+        }
+    }
     async detectDerivedStrand() {
         if (!this.lsmEngine || !this.lsmMetaDir)
             return;
@@ -1364,13 +1483,31 @@ export class MetadataIndexManager {
                     // 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) {
+                    //
+                    // UNPOSTABLE ALLOWANCE (the constant-52, CORTEX-RESTART-STRAND):
+                    // canonical rows with NO readable metadata cannot carry a
+                    // posting, and a completed rebuild PROVES which those are (each
+                    // verified by direct read) and stamps them. Without the
+                    // allowance the same cohort re-flags every boot and re-triggers
+                    // a pointless full heal forever. The stamp's ids are RE-VERIFIED
+                    // here (an id that has since gained metadata stops counting), so
+                    // the floor stays exact; beyond UNPOSTABLE_ID_CAP the stamp is
+                    // count-only and the allowance carries a bounded, logged
+                    // staleness caveat.
+                    const unpostable = await this.verifiedUnpostableAllowance();
+                    if (posted + unpostable < 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.`);
+                            `entities but the index has postings for only ${posted}` +
+                            (unpostable > 0 ? ` (+${unpostable} verified-unpostable allowance)` : '') +
+                            ` — ${canonical - posted - unpostable}+ entities are durable in ` +
+                            `canonical but UNQUERYABLE (lost postings). Reporting not-ready ` +
+                            `so the cold-open gate rebuilds from canonical.`);
+                    }
+                    else if (unpostable > 0 && posted < canonical) {
+                        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.`);
                     }
                 }
             }
@@ -1401,6 +1538,7 @@ export class MetadataIndexManager {
             idSpace: 'u64',
         });
         this.idMapperNative = handle.mapper;
+        this.idMapperCreatedFresh = handle.created;
         this.native.setIdMapper(handle.mapper);
     }
     async loadFieldRegistry() {
@@ -2401,15 +2539,23 @@ export class MetadataIndexManager {
                 for (const t of Object.values(NounType)) {
                     posted += this.native.getEntityCountByType(t);
                 }
+                // Same verified-unpostable allowance as the strand detector — a
+                // metadata-less canonical row (proven by the last completed
+                // rebuild) cannot carry a posting and must not read as damage
+                // here either, or brainy's repairIndex loops the same heal the
+                // detector fix just broke.
+                const unpostable = await this.verifiedUnpostableAllowance();
+                const floor = posted + unpostable;
                 return {
                     name: 'posted-count-floor',
-                    holds: posted >= canonical,
-                    detail: posted >= canonical
-                        ? `posted ${posted} ≥ canonical ${canonical}`
+                    holds: floor >= canonical,
+                    detail: floor >= canonical
+                        ? `posted ${posted}${unpostable > 0 ? ` (+${unpostable} verified-unpostable)` : ''} ≥ canonical ${canonical}`
                         : `canonical holds ${canonical} entities but only ${posted} are ` +
-                            `posted — ${canonical - posted} durable-but-unqueryable`,
+                            `posted (${unpostable} verified-unpostable allowed) — ` +
+                            `${canonical - floor} durable-but-unqueryable`,
                     expected: canonical,
-                    actual: posted,
+                    actual: floor,
                     heal: 'rebuild',
                 };
             },
@@ -2904,11 +3050,11 @@ export class MetadataIndexManager {
                     'function';
             if (bulkCapable)
                 this.lsmEngine.setBulkLoad(true);
-            let totalNounsProcessed;
-            let totalVerbsProcessed;
+            let nounResult;
+            let verbResult;
             try {
-                totalNounsProcessed = await this.rebuildEntityMetadata('noun');
-                totalVerbsProcessed = await this.rebuildEntityMetadata('verb');
+                nounResult = await this.rebuildEntityMetadata('noun');
+                verbResult = await this.rebuildEntityMetadata('verb');
             }
             finally {
                 // Leaving bulk mode performs the walk's single durability point
@@ -2922,7 +3068,22 @@ export class MetadataIndexManager {
             this.isRebuilding = false;
             await this.flushRebuildDirty();
             await this.flush();
-            prodLog.info(`Metadata index rebuild completed! Processed ${totalNounsProcessed} nouns and ${totalVerbsProcessed} verbs`);
+            // Persist what this COMPLETED walk PROVED unpostable (each id
+            // verified by direct canonical read) so the next boot's strand
+            // detector uses the honest floor instead of re-flagging the same
+            // cohort forever. Refreshed on every completed rebuild; an empty
+            // set clears the stamp.
+            await this.storage.saveMetadata(UNPOSTABLE_STAMP_KEY, {
+                nounCount: nounResult.noMetadata,
+                nounIds: nounResult.noMetadataIds,
+                verbCount: verbResult.noMetadata,
+                verifiedAt: Date.now(),
+            });
+            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)`
+                    : ''));
             // 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.
@@ -2950,6 +3111,7 @@ export class MetadataIndexManager {
         let processed = 0;
         let sinceFlush = 0;
         let noMetadata = 0;
+        const noMetadataIds = [];
         // Heal observability (CORTEX-RESTART-STRAND, memory's ask): a rebuild
         // must never be silent for minutes — the operator cannot distinguish
         // converging from stuck. Every 500 posted entities logs progress with
@@ -2990,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();
@@ -3000,22 +3162,25 @@ export class MetadataIndexManager {
                 }
                 else {
                     noMetadata++;
+                    if (noMetadataIds.length < UNPOSTABLE_ID_CAP)
+                        noMetadataIds.push(it.id);
                 }
             }
             hasMore = page.hasMore;
             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.`);
+                `expected only for metadata-less legacy records. First ids: ` +
+                noMetadataIds.slice(0, 10).join(', '));
         }
-        return processed;
+        return { processed, noMetadata, noMetadataIds };
     }
     /**
      * Rebuild-path verify-read for a single entity's canonical metadata.

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.16";
+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.16';
+export const COR_VERSION = '3.0.18';
 //# sourceMappingURL=version.js.map

package/package.json

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