@soulcraft/cor 3.0.15 → 3.0.17

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
@@ -554,6 +563,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
@@ -803,7 +822,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';
@@ -71,6 +73,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
@@ -189,6 +205,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 +509,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 +724,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 +809,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 +1057,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 +1114,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 +1158,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 +1187,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;
         }
@@ -1234,6 +1289,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;
@@ -1323,13 +1413,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) {
+                        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.`);
                     }
                 }
             }
@@ -1946,6 +2054,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 +2394,203 @@ 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);
+                }
+                // 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: floor >= canonical,
+                    detail: floor >= canonical
+                        ? `posted ${posted}${unpostable > 0 ? ` (+${unpostable} verified-unpostable)` : ''} ≥ canonical ${canonical}`
+                        : `canonical holds ${canonical} entities but only ${posted} are ` +
+                            `posted (${unpostable} verified-unpostable allowed) — ` +
+                            `${canonical - floor} durable-but-unqueryable`,
+                    expected: canonical,
+                    actual: floor,
+                    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
@@ -2667,11 +2979,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
@@ -2679,10 +2991,28 @@ 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`);
+            // 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(),
+            });
+            prodLog.info(`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.
@@ -2710,6 +3040,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
@@ -2760,6 +3091,8 @@ export class MetadataIndexManager {
                 }
                 else {
                     noMetadata++;
+                    if (noMetadataIds.length < UNPOSTABLE_ID_CAP)
+                        noMetadataIds.push(it.id);
                 }
             }
             hasMore = page.hasMore;
@@ -2773,9 +3106,10 @@ export class MetadataIndexManager {
             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.`);
+                `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/derivedFamilies.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module utils/derivedFamilies
+ * @description ADR-004 §7 — cor's registered-blob family declarations
+ * (adopted 2026-07-13). Each provider declares the artifact families it
+ * owns through brainy ≥8.3.0's `registerDerivedFamily` (feature-detected;
+ * inert on older adapters). Once declared, the storage layer REFUSES to
+ * delete a member (`ProtectedArtifactError` — an in-process GC/sweeper is
+ * structurally incapable of removing a load-bearing file), and
+ * `checkDerivedFamiliesPresent` names any missing-on-open member (the
+ * external-deleter catch).
+ *
+ * Scope note (deliberate split, per §7): declarations cover
+ * KEY-ADDRESSABLE artifacts — members resolve through the same adapter
+ * key→path function on both sides, so consistency is by construction.
+ * Path-level siblings the native layer writes directly (the vector
+ * base's `.slotmap`/`.slotrev` sidecars) are outside the key space; their
+ * set-coherence is cor's own `familygen` stamp (the §7 atomic set-swap),
+ * not the storage contract. Growing sets use `namespace: true` prefixes.
+ *
+ * Registration is idempotent (upsert by family name) and runs on every
+ * open. A registration failure is LOUD but never blocks an open — the
+ * contract is protective, not load-bearing.
+ */
+import type { DerivedFamilyDeclaration } from '@soulcraft/brainy';
+/**
+ * Declare families on the adapter when it supports the contract. Never
+ * throws; failures are loud. Returns how many were registered (0 when the
+ * adapter predates the contract — callers may log that once at debug).
+ */
+export declare function declareDerivedFamilies(storage: unknown, families: DerivedFamilyDeclaration[]): Promise<number>;
+/** The vector index's key-addressable families. */
+export declare const VECTOR_FAMILIES: DerivedFamilyDeclaration[];
+/** The metadata LSM's families (engine dir + SSTables share the key prefix). */
+export declare const METADATA_FAMILIES: DerivedFamilyDeclaration[];
+/** The column store's family (fully key-addressable — API delete-refusal bites here). */
+export declare const COLUMN_FAMILIES: DerivedFamilyDeclaration[];
+/** The graph index's families (LSM SSTables + verb namespace stores). */
+export declare const GRAPH_FAMILIES: DerivedFamilyDeclaration[];
+/**
+ * Owner-sanctioned retirement window (the pattern brainy's
+ * ProtectedArtifactError names): unregister the family, run the owner's
+ * legitimate delete work, re-register in a finally. The unprotected
+ * window is small and self-healing — every provider re-declares its
+ * families on init, so even a crash inside the window is repaired at the
+ * next open. On adapters without the contract, just runs `fn`.
+ */
+export declare function withFamilyRetirement<T>(storage: unknown, family: DerivedFamilyDeclaration, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=derivedFamilies.d.ts.map