@soulcraft/cor 3.0.14 → 3.0.16

package/dist/utils/NativeColumnStore.js

@@ -31,6 +31,8 @@
  * collation contract (code-point order, matching `compareCodePoints`).
  */
 import { existsSync } from 'node:fs';
+import { composeInvariantReport } from './invariantReport.js';
+import { declareDerivedFamilies, withFamilyRetirement, COLUMN_FAMILIES } from './derivedFamilies.js';
 import { prodLog } from '@soulcraft/brainy/internals';
 import { ValueType } from './columnStoreTypes.js';
 import { ColumnManifest } from './ColumnManifest.js';
@@ -145,6 +147,10 @@ export class NativeColumnStore {
                 'Use brainy FileSystemStorage or another adapter implementing BinaryBlobStorage.');
         }
         this.storage = storage;
+        // ADR-004 §7: declare the column family (feature-detected ≥8.3.0) —
+        // the one family whose members are written via saveBinaryBlob, so the
+        // storage layer's delete-refusal actively bites here.
+        await declareDerivedFamilies(storage, COLUMN_FAMILIES);
         // Discover fields by listing manifest files under the column-index prefix.
         let paths;
         try {
@@ -241,6 +247,43 @@ export class NativeColumnStore {
      * would have been invisible.
      * @param field - Field about to be served.
      */
+    /**
+     * ADR-004 §6 — the column store's invariant self-report. NEVER throws;
+     * bounded (set sizes + per-field segment counts, no IO).
+     */
+    async validateInvariants() {
+        return composeInvariantReport('column', () => this.storage !== null && this.faultedFields.size === 0, [
+            () => ({
+                name: 'fields-servable',
+                holds: this.faultedFields.size === 0,
+                detail: this.faultedFields.size === 0
+                    ? `${this.fieldTypes.size} field(s), none faulted`
+                    : `${this.faultedFields.size} field(s) UNAVAILABLE after faulted ` +
+                        `loads (queries throw): ${[...this.faultedFields].join(', ')}`,
+                expected: this.fieldTypes.size,
+                actual: this.fieldTypes.size - this.faultedFields.size,
+                heal: 'rebuild',
+            }),
+            () => {
+                // manifest-residency: every field's manifest-listed segments are
+                // attached in the native engine (hasField is the cheap proxy for
+                // a field whose segments loaded; per-segment ids are not exposed
+                // by the native surface, so the count-level check is the honest
+                // bounded version — a faulted segment already trips
+                // fields-servable above).
+                const unattached = [...this.manifests.keys()].filter((field) => !this.faultedFields.has(field) && !this.native.hasField(field));
+                return {
+                    name: 'manifest-residency',
+                    holds: unattached.length === 0,
+                    detail: unattached.length === 0
+                        ? `${this.manifests.size} field manifest(s), all attached`
+                        : `${unattached.length} field(s) have persisted manifests but no ` +
+                            `attached native state: ${unattached.join(', ')}`,
+                    heal: 'rebuild',
+                };
+            },
+        ]);
+    }
     assertFieldServable(field) {
         if (this.faultedFields.has(field)) {
             throw new Error(`NativeColumnStore: column index for field '${field}' is UNAVAILABLE — ` +
@@ -464,18 +507,25 @@ export class NativeColumnStore {
         // Delete persisted column-index files (manifests + segment/deleted blobs)
         // before dropping the in-memory manifests we need to locate them.
         if (this.storage) {
-            for (const [field, manifest] of this.manifests) {
-                try {
-                    await this.storage.deleteObjectFromPath(manifest.manifestPath());
-                }
-                catch {
-                    /* manifest already gone */
-                }
-                for (const seg of manifest.getAllSegments()) {
-                    await this.storage.deleteBinaryBlob(segmentBlobKey(field, seg.level, seg.id));
+            // Owner-sanctioned retirement (ADR-004 §7): this reset legitimately
+            // deletes the family's own members (a rebuild reassigns entity ints,
+            // invalidating old segments), so the protection window opens and
+            // closes around exactly this loop.
+            const storage = this.storage;
+            await withFamilyRetirement(storage, COLUMN_FAMILIES[0], async () => {
+                for (const [field, manifest] of this.manifests) {
+                    try {
+                        await storage.deleteObjectFromPath(manifest.manifestPath());
+                    }
+                    catch {
+                        /* manifest already gone */
+                    }
+                    for (const seg of manifest.getAllSegments()) {
+                        await storage.deleteBinaryBlob(segmentBlobKey(field, seg.level, seg.id));
+                    }
+                    await storage.deleteBinaryBlob(deletedBlobKey(field));
                 }
-                await this.storage.deleteBinaryBlob(deletedBlobKey(field));
-            }
+            });
         }
         // Drop all native state by replacing the engine, then clear TS-side state.
         // Faults clear too: the rebuild that follows repopulates every field

package/dist/utils/NativeMetadataIndex.d.ts

@@ -17,6 +17,7 @@
  */
 import type { StorageAdapter } from '@soulcraft/brainy';
 import { NounType, VerbType } from '@soulcraft/brainy/types/graphTypes';
+import type { ProviderInvariantReport } from '@soulcraft/brainy';
 import { NativeColumnStore } from './NativeColumnStore.js';
 import type { EntityIdMapperLike } from './columnStoreTypes.js';
 import type { MetadataIndexProvider } from '../providerContracts.js';
@@ -115,6 +116,14 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      * everything from canonical. Cleared by a completed {@link rebuild}.
      */
     private strandDetected;
+    /**
+     * SSTable ids actually REGISTERED into the live engine (cold-open
+     * registration + post-flush registration). The `manifest-residency`
+     * invariant (ADR-004 §6) compares the persisted manifest's claims
+     * against this set — the manifest is a claim; registration is the truth.
+     * Cleared on the rebuild's fresh re-open.
+     */
+    private lsmRegisteredSstableIds;
     /**
      * **#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
@@ -803,7 +812,28 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
     getAllVFSEntityCounts(): Promise<Map<string, number>>;
     getTotalVFSEntityCount(): Promise<number>;
     getCountForCriteria(field: string, value: any): Promise<number>;
+    /**
+     * ADR-004 §6 — the provider's self-report of its cross-layer invariants.
+     * NEVER throws; bounded (residency + O(1) count reads, one limit-1
+     * canonical probe); safe on a live brain. Brainy's
+     * `validateIndexConsistency` feature-detects and aggregates this;
+     * `repairIndex` maps `heal: 'rebuild'` failures to {@link rebuild}.
+     */
+    validateInvariants(): Promise<ProviderInvariantReport>;
+    /**
+     * Serializes every {@link flush} pass. Two flushes interleaving at the
+     * awaits is NOT hypothetical — memory-vm runs a periodic flusher AND
+     * brainy's shutdown hook flushes on SIGTERM — and the flushLsm pair
+     * both read `nextSstableId(manifest)` before either pushes: SAME id →
+     * same blob key → the second write OVERWRITES the first SSTable →
+     * postings lost with clean logs and NO replay anomaly (the exact
+     * acceptance-#1 signature on CORTEX-RESTART-STRAND, 2026-07-13).
+     * Chaining gives each caller its own full pass covering everything
+     * written before its call — the semantics a shutdown flush needs.
+     */
+    private flushChain;
     flush(): Promise<void>;
+    private flushOnce;
     /**
      * Persist all state and release the column store's resources. Brainy's
      * shutdown path calls `metadataIndex.close()` when present; flushing here

package/dist/utils/NativeMetadataIndex.js

@@ -34,6 +34,8 @@ 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 { declareDerivedFamilies, METADATA_FAMILIES } from './derivedFamilies.js';
 import { openOrCreateBinaryIdMapper } from './binaryIdMapperFactory.js';
 import { NativeColumnStore } from './NativeColumnStore.js';
 import { ResourceManager } from '../resource/ResourceManager.js';
@@ -189,6 +191,14 @@ export class MetadataIndexManager {
      * everything from canonical. Cleared by a completed {@link rebuild}.
      */
     strandDetected = false;
+    /**
+     * SSTable ids actually REGISTERED into the live engine (cold-open
+     * registration + post-flush registration). The `manifest-residency`
+     * invariant (ADR-004 §6) compares the persisted manifest's claims
+     * against this set — the manifest is a claim; registration is the truth.
+     * Cleared on the rebuild's fresh re-open.
+     */
+    lsmRegisteredSstableIds = new Set();
     /**
      * **#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
@@ -485,6 +495,7 @@ export class MetadataIndexManager {
                     throw new Error(`openLsmEngine: getBinaryBlobPath returned null for persisted SSTable '${key}'`);
                 }
                 engine.registerSstablePath(path);
+                this.lsmRegisteredSstableIds.add(entry.id);
             }
         }
         // Cold-open replay forensics (CORTEX-RESTART-STRAND). The engine's
@@ -699,6 +710,7 @@ export class MetadataIndexManager {
         });
         this.lsmEngine = engine;
         this.lsmManifest = newEmptyLsmManifest();
+        this.lsmRegisteredSstableIds.clear();
         this.native.setLsmEngine(engine);
         // Re-apply the current admission ceiling immediately (the subscriber
         // callback only refreshes it on the next rebalance/pressure tick). The
@@ -783,6 +795,7 @@ export class MetadataIndexManager {
             throw new Error(`flushLsm: getBinaryBlobPath returned null for '${key}'`);
         }
         engine.registerSstablePath(path);
+        this.lsmRegisteredSstableIds.add(id);
         // (4) Retire the memtable log below the flushed epoch. The `.sst` bytes
         // AND the manifest referencing them are already durable here, so a failure
         // at THIS step is non-fatal per the ordering invariant above: the records
@@ -1030,15 +1043,29 @@ export class MetadataIndexManager {
             getUuid: (intId) => native.intToUuid(intId) ?? undefined,
             getInt: (uuid) => native.uuidToInt(uuid) ?? undefined,
             getOrAssign: (uuid) => {
-                // The native index assigns ids inside addToIndex. If a caller resolves an
-                // id before the entity is indexed, surface the existing mapping; an
-                // unmapped UUID has no int id yet and is reported as such rather than
-                // fabricating one (which would desync the canonical native mapper).
+                // The native index assigns ids inside addToIndex; a mapped UUID
+                // resolves to its existing int. An UNMAPPED uuid here is a
+                // canonical-committed entity whose index ops were lost (the
+                // restart-strand class — memory's boot heal hit exactly this,
+                // CORTEX-RESTART-STRAND 2026-07-13): the cold vector rebuild
+                // walks canonical and must be able to MINT the id through the
+                // SAME allocator addToIndex uses (durable via the mapper's delta
+                // log; a later addToIndex reuses it) instead of aborting the
+                // whole heal. The entity's missing metadata postings stay
+                // visible to posted-count-floor — this masks nothing.
                 const existing = native.uuidToInt(uuid);
                 if (existing !== null)
                     return existing;
-                throw new Error(`EntityIdMapper.getOrAssign: '${uuid}' has no native id yet — ids are ` +
-                    `assigned by addToIndex. Index the entity before resolving its int id.`);
+                if (typeof native.getOrAssignInt === 'function') {
+                    prodLog.warn(`EntityIdMapper.getOrAssign: '${uuid}' had no native id at resolve ` +
+                        `time (canonical-committed entity with lost index ops) — assigned ` +
+                        `through the canonical allocator; its metadata postings heal via ` +
+                        `the posted-count invariant / rebuild.`);
+                    return Number(native.getOrAssignInt(uuid));
+                }
+                throw new Error(`EntityIdMapper.getOrAssign: '${uuid}' has no native id yet and the ` +
+                    `loaded native binary predates 3.0.16's getOrAssignInt — upgrade ` +
+                    `the paired .node build.`);
             },
             intsIterableToUuids: (ints) => native.intsToUuids([...ints]),
             // Brainy 8.0 `restore()` calls this BEFORE the metadata/vector/graph
@@ -1073,6 +1100,9 @@ export class MetadataIndexManager {
         // UUID ↔ entity-int allocator. Must run before columnStore.init (which
         // resolves ids through getIdMapper()) and before any mutation.
         this.wireIdMapper();
+        // ADR-004 §7: declare this provider's protected families (feature-
+        // detected on brainy ≥8.3.0; idempotent upsert; loud-but-non-blocking).
+        await declareDerivedFamilies(this.storage, METADATA_FAMILIES);
         // LSM durability (steps 3-4): open the native LSM engine here (not in the
         // constructor) so it can be seeded from the on-disk manifest and cold-load
         // every persisted SSTable into its live read set — the entire restore,
@@ -1114,6 +1144,7 @@ export class MetadataIndexManager {
                         prodLog.info('[NativeMetadataIndex] Field registry missing but the LSM engine ' +
                             'recovered durable state (SSTables/memtable) — serving from it, ' +
                             'NO rebuild.');
+                        this.readinessInitialized = true;
                         return;
                     }
                     // **Tripwire — a rebuild here on a PREVIOUSLY-HEALTHY brain is a bug,
@@ -1142,11 +1173,21 @@ export class MetadataIndexManager {
                     }
                     console.warn(`[NativeMetadataIndex] Field registry missing but ${probe.totalCount ?? 'unknown'} entities exist — rebuilding index`);
                     await this.rebuild();
+                    // A completed rebuild IS the readiness determination for this
+                    // open (sweep finding: these early exits previously left
+                    // readinessInitialized false — a fresh-rebuilt brain reported
+                    // not-ready forever, and brainy's gate re-rebuilt every boot).
+                    this.readinessInitialized = true;
                     return;
                 }
+                // Probe says genuinely empty — an empty brain is READY by contract.
+                this.readinessInitialized = true;
             }
             catch {
-                // Storage probe failed — genuinely empty
+                // Storage probe failed — treated as empty per current semantics;
+                // readiness stays UNINITIALIZED (conservative: a faulted probe must
+                // not certify an unverified brain as ready — the fault-vs-absent
+                // discrimination for this probe is tracked ADR-004 §4 M-work).
             }
             return;
         }
@@ -1946,6 +1987,14 @@ export class MetadataIndexManager {
             const resultJson = this.native.removeFromIndex(id);
             const result = JSON.parse(resultJson);
             await this.persistMutationResult(result);
+            // Count symmetry (sweep finding; ADR-004 anti-pattern C): this path
+            // has no metadata to know WHICH type to decrement, and skipping the
+            // decrement permanently inflated totalEntitiesByType /
+            // entityCountsByTypeFixed until restart. Instead of guessing,
+            // RECOMPUTE the counters from native ground truth — bounded
+            // (per-type O(1) bitmap-cardinality reads, no id materialization).
+            await this.lazyLoadCounts();
+            this.syncTypeCountsToFixed();
         }
         // Tombstone in the column store so the entity drops out of sort/filter/range.
         if (intId !== null) {
@@ -2278,7 +2327,195 @@ export class MetadataIndexManager {
     // ==========================================================================
     // Flush
     // ==========================================================================
+    /**
+     * ADR-004 §6 — the provider's self-report of its cross-layer invariants.
+     * NEVER throws; bounded (residency + O(1) count reads, one limit-1
+     * canonical probe); safe on a live brain. Brainy's
+     * `validateIndexConsistency` feature-detects and aggregates this;
+     * `repairIndex` maps `heal: 'rebuild'` failures to {@link rebuild}.
+     */
+    async validateInvariants() {
+        return composeInvariantReport('metadata', () => this.isReady(), [
+            // manifest-residency: every persisted-manifest-named SSTable is
+            // actually registered in the live engine.
+            () => {
+                const manifest = this.lsmManifest;
+                if (manifest === null || this.lsmMetaDir === null) {
+                    return {
+                        name: 'manifest-residency',
+                        holds: true,
+                        detail: 'in-RAM engine or fresh brain — no persisted SSTables to verify',
+                        heal: 'none',
+                    };
+                }
+                const missing = manifest.sstables
+                    .map((e) => e.id)
+                    .filter((id) => !this.lsmRegisteredSstableIds.has(id));
+                return {
+                    name: 'manifest-residency',
+                    holds: missing.length === 0,
+                    detail: missing.length === 0
+                        ? `${manifest.sstables.length} manifest-named SSTable(s), all registered`
+                        : `manifest names ${manifest.sstables.length} SSTable(s) but ` +
+                            `${missing.length} never registered (ids: ${missing.join(', ')}) — ` +
+                            `the index serves a subset of its durable postings`,
+                    expected: manifest.sstables.length,
+                    actual: manifest.sstables.length - missing.length,
+                    heal: 'rebuild',
+                };
+            },
+            // posted-count-floor: Σ posted noun counts ≥ canonical noun count.
+            async () => {
+                const getNouns = this.storage.getNouns;
+                if (typeof getNouns !== 'function') {
+                    return {
+                        name: 'posted-count-floor',
+                        holds: true,
+                        detail: 'adapter exposes no getNouns — floor unverifiable, skipped',
+                        heal: 'none',
+                    };
+                }
+                let canonical;
+                try {
+                    const probe = await getNouns.call(this.storage, { pagination: { limit: 1 } });
+                    canonical = probe?.totalCount;
+                }
+                catch (error) {
+                    return {
+                        name: 'posted-count-floor',
+                        holds: false,
+                        detail: `canonical count probe FAULTED — divergence unverifiable: ${String(error)}`,
+                        heal: 'none',
+                    };
+                }
+                if (typeof canonical !== 'number' || !Number.isFinite(canonical) || canonical >= 0xffff_ffff) {
+                    return {
+                        name: 'posted-count-floor',
+                        holds: true,
+                        detail: `canonical count not exactly countable (${String(canonical)}) — floor skipped by design`,
+                        heal: 'none',
+                    };
+                }
+                const { NounType } = await import('@soulcraft/brainy');
+                let posted = 0;
+                for (const t of Object.values(NounType)) {
+                    posted += this.native.getEntityCountByType(t);
+                }
+                return {
+                    name: 'posted-count-floor',
+                    holds: posted >= canonical,
+                    detail: posted >= canonical
+                        ? `posted ${posted} ≥ canonical ${canonical}`
+                        : `canonical holds ${canonical} entities but only ${posted} are ` +
+                            `posted — ${canonical - posted} durable-but-unqueryable`,
+                    expected: canonical,
+                    actual: posted,
+                    heal: 'rebuild',
+                };
+            },
+            // replay-clean: the cold open recovered nothing anomalous.
+            () => {
+                const engine = this.lsmEngine;
+                if (!engine || typeof engine.replayStatsJson !== 'function') {
+                    return {
+                        name: 'replay-clean',
+                        holds: true,
+                        detail: 'replay stats unavailable (in-RAM engine or pre-3.0.12 binary)',
+                        heal: 'none',
+                    };
+                }
+                const s = JSON.parse(engine.replayStatsJson());
+                const unreadable = s.archivesUnreadable ?? 0;
+                const recreated = s.liveLogsRecreated ?? 0;
+                const clean = unreadable === 0 && recreated === 0;
+                return {
+                    name: 'replay-clean',
+                    holds: clean,
+                    detail: clean
+                        ? 'cold-open replay clean (no unreadable archives, no recreated live logs)'
+                        : `cold-open replay anomalies: ${recreated} live log(s) were missing ` +
+                            `(recreated), ${unreadable} archive(s) unreadable`,
+                    heal: 'rebuild',
+                };
+            },
+            // registry-discoverable: every field this process knows is in the
+            // persisted registry a cold open would discover.
+            async () => {
+                if (this.knownFields.size === 0) {
+                    return {
+                        name: 'registry-discoverable',
+                        holds: true,
+                        detail: 'no fields registered yet',
+                        heal: 'none',
+                    };
+                }
+                let persisted = [];
+                try {
+                    const raw = await this.storage.getMetadata('__metadata_field_registry__');
+                    persisted = Array.isArray(raw?.fields)
+                        ? (raw.fields)
+                        : Array.isArray(raw)
+                            ? raw
+                            : [];
+                }
+                catch (error) {
+                    return {
+                        name: 'registry-discoverable',
+                        holds: false,
+                        detail: `persisted registry read FAULTED — discoverability unverifiable: ${String(error)}`,
+                        heal: 'none',
+                    };
+                }
+                const persistedSet = new Set(persisted);
+                const undiscoverable = [...this.knownFields].filter((f) => !persistedSet.has(f));
+                return {
+                    name: 'registry-discoverable',
+                    holds: undiscoverable.length === 0,
+                    detail: undiscoverable.length === 0
+                        ? `${this.knownFields.size} known field(s), all in the persisted registry`
+                        : `${undiscoverable.length} known field(s) missing from the persisted ` +
+                            `registry (would be undiscoverable after restart): ${undiscoverable.join(', ')}`,
+                    expected: this.knownFields.size,
+                    actual: this.knownFields.size - undiscoverable.length,
+                    heal: 'repair',
+                };
+            },
+        ]);
+    }
+    /**
+     * Serializes every {@link flush} pass. Two flushes interleaving at the
+     * awaits is NOT hypothetical — memory-vm runs a periodic flusher AND
+     * brainy's shutdown hook flushes on SIGTERM — and the flushLsm pair
+     * both read `nextSstableId(manifest)` before either pushes: SAME id →
+     * same blob key → the second write OVERWRITES the first SSTable →
+     * postings lost with clean logs and NO replay anomaly (the exact
+     * acceptance-#1 signature on CORTEX-RESTART-STRAND, 2026-07-13).
+     * Chaining gives each caller its own full pass covering everything
+     * written before its call — the semantics a shutdown flush needs.
+     */
+    flushChain = Promise.resolve();
     async flush() {
+        // Flush-during-rebuild guard (CORTEX-RESTART-STRAND, memory-vm's
+        // 80-minute heal): a consumer's periodic flush cycle running DURING a
+        // rebuild drains the growing memtable + rewrites field indexes on
+        // every pass — O(current-index-size) IO per pass, interleaved with the
+        // walk (measured live: 572 msync/s + escalating 29s→45s flush passes).
+        // The rebuild's own completion flush owns durability (canonical is the
+        // source of truth throughout), so a concurrent flush only multiplies
+        // IO. Loud no-op, never silent.
+        if (this.isRebuilding) {
+            prodLog.warn('[NativeMetadataIndex] flush() during an active rebuild — deferred ' +
+                '(the rebuild\'s completion flush owns durability; a concurrent ' +
+                'flush would multiply heal IO).');
+            return;
+        }
+        const run = this.flushChain.then(() => this.flushOnce());
+        // Keep the chain alive on failure — the NEXT flush must still run; the
+        // failure itself propagates to THIS caller below.
+        this.flushChain = run.catch(() => { });
+        return run;
+    }
+    async flushOnce() {
         // Always save field registry + msync the entity ID mapper — even with
         // no dirty fields. The field registry is the critical file init() needs
         // to discover persisted indices. Without it, the metadata index appears
@@ -2679,7 +2916,10 @@ export class MetadataIndexManager {
                 if (bulkCapable)
                     this.lsmEngine.setBulkLoad(false);
             }
-            // Final flush
+            // Final flush. isRebuilding drops FIRST so the completion flush
+            // passes the flush-during-rebuild guard above; readiness is still
+            // gated by strandDetected until the flush lands and clears it below.
+            this.isRebuilding = false;
             await this.flushRebuildDirty();
             await this.flush();
             prodLog.info(`Metadata index rebuild completed! Processed ${totalNounsProcessed} nouns and ${totalVerbsProcessed} verbs`);
@@ -2710,13 +2950,27 @@ export class MetadataIndexManager {
         let processed = 0;
         let sinceFlush = 0;
         let noMetadata = 0;
+        // 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
+        // the sustained rate, so a pathological per-item cost names itself in
+        // the journal in real time.
+        const startedAt = Date.now();
+        let lastProgressAt = 0;
+        const fetchPage = (c) => kind === 'noun'
+            ? this.storage.getNouns({ pagination: { limit: PAGE, cursor: c } })
+            : this.storage.getVerbs({ pagination: { limit: PAGE, cursor: c } });
+        // Prefetch pipeline: the NEXT canonical page is fetched while the
+        // CURRENT page indexes, so adapter enumeration latency overlaps the
+        // RAM-speed posting work instead of adding to it.
+        let pending = fetchPage(cursor);
         while (hasMore) {
-            const page = kind === 'noun'
-                ? await this.storage.getNouns({ pagination: { limit: PAGE, cursor } })
-                : await this.storage.getVerbs({ pagination: { limit: PAGE, cursor } });
+            const page = await pending;
             const items = page.items;
             if (items.length === 0)
                 break; // empty page = done (defensive backstop)
+            if (page.hasMore)
+                pending = fetchPage(page.nextCursor);
             const ids = items.map((it) => it.id);
             const md = await this.loadRebuildMetadataBatch(kind, ids);
             for (const it of items) {
@@ -2733,6 +2987,12 @@ export class MetadataIndexManager {
                 if (metadata) {
                     await this.addToIndex(it.id, metadata, true, true);
                     processed++;
+                    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)`);
+                    }
                     if (++sinceFlush >= 5000) {
                         await this.flushRebuildDirty();
                         sinceFlush = 0;
@@ -2743,9 +3003,12 @@ export class MetadataIndexManager {
                 }
             }
             hasMore = page.hasMore;
-            cursor = page.nextCursor;
             await this.yieldToEventLoop();
         }
+        const totalS = (Date.now() - startedAt) / 1000;
+        prodLog.info(`[NativeMetadataIndex] 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 ` +
                 `entit${noMetadata === 1 ? 'y' : 'ies'} carried no canonical ` +
@@ -2793,16 +3056,29 @@ export class MetadataIndexManager {
         else if (this.storage.getVerbMetadataBatch) {
             return this.storage.getVerbMetadataBatch(ids);
         }
+        // Bounded-concurrency reads (16-way). The reads are independent, and a
+        // SERIAL per-id walk multiplies the adapter's per-op latency by N — on
+        // a slow adapter (memory-vm measured ~1s/op shapes) that turned a
+        // seconds-long heal into ~1s/entity (CORTEX-RESTART-STRAND, the
+        // 52-minute heal). Concurrency divides heal time by ~16 on ANY
+        // adapter; fail-loud is preserved (a faulted read rejects the whole
+        // batch via Promise.all — readRebuildMetadataOrThrow retries once then
+        // throws, never silently excludes).
         const m = new Map();
-        for (const id of ids) {
-            // 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);
-        }
+        const CONCURRENCY = 16;
+        let next = 0;
+        const workers = Array.from({ length: Math.min(CONCURRENCY, ids.length) }, async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= ids.length)
+                    break;
+                const id = ids[i];
+                const md = await this.readRebuildMetadataOrThrow(kind, id);
+                if (md)
+                    m.set(id, md);
+            }
+        });
+        await Promise.all(workers);
         return m;
     }
     /**

package/dist/utils/binaryIdMapperFactory.js

@@ -15,7 +15,7 @@
  * brain pays only for what it uses. This is the constant-RAM,
  * billion-scale store that replaces the resident JSON id-maps (#72).
  */
-import { existsSync } from 'node:fs';
+import { statSync } from 'node:fs';
 import { loadNativeModule } from '../native/index.js';
 /** Default storage key for the extendible-hash UUID → int file. */
 export const DEFAULT_UUID_TO_INT_KEY = '_id_mapper/uuid_to_int.mkv';
@@ -65,10 +65,17 @@ export function openOrCreateBinaryIdMapper(storage, opts = {}) {
     // Both files must exist together (paired write semantics). A
     // half-present state is crash corruption surfaced as an error,
     // never silently recreated.
+    //
+    // Fault-vs-absent (spine ADR-004 §4): the probes below THROW on any stat
+    // fault other than a clean ENOENT. `existsSync` returned false on
+    // EACCES/EIO/EMFILE too — and a double false routed to `create()`, which
+    // TRUNCATES both stores: a transient permissions blip (backup tool,
+    // scanner, remount) could wipe the brain's entire UUID↔int allocator.
+    // Deciding open-vs-create is only legal on certain knowledge.
     let mapper;
     let created;
-    const uuidFileExists = existsSync(uuidToIntPath);
-    const intFileExists = existsSync(intToUuidPath);
+    const uuidFileExists = durableFilePresent(uuidToIntPath, uuidToIntKey);
+    const intFileExists = durableFilePresent(intToUuidPath, intToUuidKey);
     if (uuidFileExists && intFileExists) {
         mapper = NativeBinaryIdMapper.openExisting(config);
         created = false;
@@ -91,4 +98,27 @@ export function openOrCreateBinaryIdMapper(storage, opts = {}) {
         created,
     };
 }
+/**
+ * Fault-discriminating existence probe for the id-mapper stores (spine
+ * ADR-004 §4). Returns `true`/`false` only on CERTAIN knowledge; any stat
+ * fault other than a clean ENOENT throws — because the caller's "neither
+ * file exists" branch invokes `create()`, which TRUNCATES, and a transient
+ * EACCES/EIO must never be allowed to masquerade as a fresh brain.
+ */
+function durableFilePresent(path, key) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return false;
+        throw new Error(`openOrCreateBinaryIdMapper: existence probe FAULTED for '${key}' ` +
+            `(${code ?? 'unknown'}) — refusing to decide open-vs-create on a ` +
+            `fault (create() truncates the brain's id allocator; a transient ` +
+            `IO/permissions fault must never wipe it). Restore storage health ` +
+            `and reopen. Cause: ${String(error)}`);
+    }
+}
 //# sourceMappingURL=binaryIdMapperFactory.js.map