@soulcraft/cor 3.0.15 → 3.0.16

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`);

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

package/dist/utils/derivedFamilies.js

@@ -0,0 +1,128 @@
+/**
+ * @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 { prodLog } from '@soulcraft/brainy/internals';
+/**
+ * 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 async function declareDerivedFamilies(storage, families) {
+    const s = storage;
+    if (typeof s?.registerDerivedFamily !== 'function')
+        return 0;
+    let registered = 0;
+    for (const family of families) {
+        try {
+            await s.registerDerivedFamily(family);
+            registered++;
+        }
+        catch (error) {
+            prodLog.error(`[cor] registerDerivedFamily('${family.name}') FAILED — its members ` +
+                `are NOT delete-protected this session (opens are unaffected):`, error);
+        }
+    }
+    return registered;
+}
+/** The vector index's key-addressable families. */
+export const VECTOR_FAMILIES = [
+    {
+        name: 'vector-base',
+        members: ['_system/vector-index/main.dkann'],
+        rebuildable: true,
+    },
+    {
+        name: 'vector-segments',
+        members: ['_system/vector-index/seg-'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/** The metadata LSM's families (engine dir + SSTables share the key prefix). */
+export const METADATA_FAMILIES = [
+    {
+        name: 'metadata-lsm',
+        members: ['_metadata'],
+        namespace: true,
+        rebuildable: true,
+    },
+    {
+        name: 'id-mapper',
+        members: ['_id_mapper/'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/** The column store's family (fully key-addressable — API delete-refusal bites here). */
+export const COLUMN_FAMILIES = [
+    {
+        name: 'column-index',
+        members: ['_column_index/'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/** The graph index's families (LSM SSTables + verb namespace stores). */
+export const GRAPH_FAMILIES = [
+    {
+        name: 'graph-lsm',
+        members: ['graph-lsm/'],
+        namespace: true,
+        rebuildable: true,
+    },
+    {
+        name: 'graph-verb-namespace',
+        members: ['_graph_verb_ns/'],
+        namespace: true,
+        rebuildable: true,
+    },
+];
+/**
+ * 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 async function withFamilyRetirement(storage, family, fn) {
+    const s = storage;
+    if (typeof s?.unregisterDerivedFamily !== 'function' ||
+        typeof s?.registerDerivedFamily !== 'function') {
+        return fn();
+    }
+    await s.unregisterDerivedFamily(family.name);
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            await s.registerDerivedFamily(family);
+        }
+        catch (error) {
+            prodLog.error(`[cor] re-register of family '${family.name}' after retirement ` +
+                `FAILED — protection resumes at the next open:`, error);
+        }
+    }
+}
+//# sourceMappingURL=derivedFamilies.js.map

package/dist/utils/invariantReport.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module utils/invariantReport
+ * @description Shared composer for the ADR-004 §6 `validateInvariants()`
+ * hook (adopted 2026-07-13, decision `adr-004-write-index-spine-adoption`).
+ * Every cor provider builds its report through this so the contract holds
+ * uniformly: the hook NEVER throws (a thrown check is surfaced as a failing
+ * invariant naming the throw — never an exception, never swallowed), stays
+ * bounded (checks are residency + O(1) counts only; the composer measures
+ * and reports duration), and failures carry named, numbered detail.
+ *
+ * Types are imported from brainy 8.3.0's published surface so both engines
+ * share one wire shape (`ProviderInvariantReport` / `InvariantResult` /
+ * `InvariantHeal` — brainy's `validateIndexConsistency` feature-detects the
+ * hook and aggregates these verbatim; `repairIndex` maps `heal: 'rebuild'`
+ * to the provider's own rebuild).
+ */
+import type { InvariantResult, ProviderInvariantReport } from '@soulcraft/brainy';
+/** One invariant check: returns its result, sync or async. A throw is a
+ * contract violation the composer converts into a failing invariant. */
+export type InvariantCheck = () => InvariantResult | Promise<InvariantResult>;
+/**
+ * Run every check, never throw, stamp timing. A check that throws becomes
+ * `holds: false` with `heal: 'none'` and detail naming the throw — the
+ * never-throws contract surfaced as unhealthy data rather than an exception
+ * (and `heal: 'none'` so a flaky probe can never trigger a spurious
+ * rebuild; visibility without overreaction).
+ */
+export declare function composeInvariantReport(provider: string, serving: () => boolean, checks: InvariantCheck[]): Promise<ProviderInvariantReport>;
+//# sourceMappingURL=invariantReport.d.ts.map

package/dist/utils/invariantReport.js

@@ -0,0 +1,62 @@
+/**
+ * @module utils/invariantReport
+ * @description Shared composer for the ADR-004 §6 `validateInvariants()`
+ * hook (adopted 2026-07-13, decision `adr-004-write-index-spine-adoption`).
+ * Every cor provider builds its report through this so the contract holds
+ * uniformly: the hook NEVER throws (a thrown check is surfaced as a failing
+ * invariant naming the throw — never an exception, never swallowed), stays
+ * bounded (checks are residency + O(1) counts only; the composer measures
+ * and reports duration), and failures carry named, numbered detail.
+ *
+ * Types are imported from brainy 8.3.0's published surface so both engines
+ * share one wire shape (`ProviderInvariantReport` / `InvariantResult` /
+ * `InvariantHeal` — brainy's `validateIndexConsistency` feature-detects the
+ * hook and aggregates these verbatim; `repairIndex` maps `heal: 'rebuild'`
+ * to the provider's own rebuild).
+ */
+/**
+ * Run every check, never throw, stamp timing. A check that throws becomes
+ * `holds: false` with `heal: 'none'` and detail naming the throw — the
+ * never-throws contract surfaced as unhealthy data rather than an exception
+ * (and `heal: 'none'` so a flaky probe can never trigger a spurious
+ * rebuild; visibility without overreaction).
+ */
+export async function composeInvariantReport(provider, serving, checks) {
+    const startedAt = Date.now();
+    const invariants = [];
+    for (const check of checks) {
+        try {
+            invariants.push(await check());
+        }
+        catch (error) {
+            invariants.push({
+                name: 'check-integrity',
+                holds: false,
+                detail: `an invariant check THREW (contract violation — checks must ` +
+                    `return failures as data): ${String(error)}`,
+                heal: 'none',
+            });
+        }
+    }
+    let servingNow = false;
+    try {
+        servingNow = serving();
+    }
+    catch (error) {
+        invariants.push({
+            name: 'serving-probe',
+            holds: false,
+            detail: `isReady() itself threw: ${String(error)}`,
+            heal: 'none',
+        });
+    }
+    return {
+        provider,
+        healthy: invariants.every((i) => i.holds),
+        serving: servingNow,
+        invariants,
+        checkedAt: startedAt,
+        durationMs: Date.now() - startedAt,
+    };
+}
+//# sourceMappingURL=invariantReport.js.map