@soulcraft/cor 3.0.15 → 3.0.17

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -17,6 +17,7 @@ import type { NativeGraphAdjacencyInstance } from '../native/types.js';
 import type { GraphIndexProvider } from '../providerContracts.js';
 import type { EntityIdMapperLike } from '../utils/columnStoreTypes.js';
 import type { MigrationCoordinator, MigrationStatus } from '../migration/MigrationCoordinator.js';
+import type { ProviderInvariantReport } from '@soulcraft/brainy';
 export interface GraphIndexConfig {
     maxIndexSize?: number;
     rebuildThreshold?: number;
@@ -262,6 +263,12 @@ export declare class GraphAdjacencyIndex implements GraphIndexProvider {
      * genuinely EMPTY — distinguished from "edges exist on disk but didn't load"
      * (which must still rebuild) via the persisted SSTable + memtable counts.
      */
+    /**
+     * ADR-004 §6 — the graph provider's invariant self-report. NEVER throws;
+     * bounded (one native stats read + two flags). Brainy aggregates via
+     * `validateIndexConsistency`; `heal: 'rebuild'` maps to {@link rebuild}.
+     */
+    validateInvariants(): Promise<ProviderInvariantReport>;
     isReady(): boolean;
     /**
      * @description **#18 migration lock — feature-detected by Brainy.** `true` while

package/dist/graph/NativeGraphAdjacencyIndex.js

@@ -15,6 +15,8 @@
 import { dirname } from 'node:path';
 import { TypeUtils, VerbType } from '@soulcraft/brainy/types/graphTypes';
 import { loadNativeModule } from '../native/index.js';
+import { composeInvariantReport } from '../utils/invariantReport.js';
+import { declareDerivedFamilies, withFamilyRetirement, GRAPH_FAMILIES } from '../utils/derivedFamilies.js';
 import { getGlobalCache, prodLog } from '@soulcraft/brainy/internals';
 /**
  * Fallback verb-type index for unknown / missing verb-type strings.
@@ -216,6 +218,8 @@ export class GraphAdjacencyIndex {
      * an index that is never `init()`-ed still cold-loads on first touch.
      */
     async init() {
+        // ADR-004 §7: declare the graph families (feature-detected ≥8.3.0).
+        await declareDerivedFamilies(this.storage, GRAPH_FAMILIES);
         await this.ensureInitialized();
     }
     /**
@@ -561,6 +565,43 @@ export class GraphAdjacencyIndex {
      * genuinely EMPTY — distinguished from "edges exist on disk but didn't load"
      * (which must still rebuild) via the persisted SSTable + memtable counts.
      */
+    /**
+     * ADR-004 §6 — the graph provider's invariant self-report. NEVER throws;
+     * bounded (one native stats read + two flags). Brainy aggregates via
+     * `validateIndexConsistency`; `heal: 'rebuild'` maps to {@link rebuild}.
+     */
+    async validateInvariants() {
+        return composeInvariantReport('graph', () => this.isReady(), [
+            () => {
+                const raw = this.native.getStats();
+                const s = (typeof raw === 'string' ? JSON.parse(raw) : raw);
+                if (s.loadComplete === undefined) {
+                    return {
+                        name: 'manifest-residency',
+                        holds: true,
+                        detail: 'binary predates residency stats (pre-3.0.13) — unverifiable here',
+                        heal: 'none',
+                    };
+                }
+                return {
+                    name: 'manifest-residency',
+                    holds: s.loadComplete,
+                    detail: s.loadComplete
+                        ? 'every manifest-named SSTable resident across all four trees'
+                        : 'a manifest-named SSTable is NOT resident — the graph would serve a subset of its edges',
+                    heal: 'rebuild',
+                };
+            },
+            () => ({
+                name: 'canonical-coverage',
+                holds: !this.canonicalUnindexed,
+                detail: this.canonicalUnindexed
+                    ? 'canonical verbs exist with no durable graph state (migration/restore shape) — a rebuild is required'
+                    : 'no canonical-vs-durable coverage gap detected',
+                heal: 'rebuild',
+            }),
+        ]);
+    }
     isReady() {
         if (this.native.isReady())
             return true;
@@ -974,13 +1015,22 @@ export class GraphAdjacencyIndex {
                 //    just leaves orphans, never a missing-blob error.
                 await this.saveTreeManifest(treeName, prefix);
                 // 3. Delete old blobs (best-effort orphan cleanup AFTER the
-                //    manifest no longer references them). Failures here are
-                //    harmless — the worst outcome is leaked disk space until
-                //    a future operator-level GC sweep.
-                for (const oldId of result.oldIds) {
-                    const oldBlobKey = this.blobKey(treeName, oldId);
-                    this.storage.deleteBinaryBlob(oldBlobKey).catch(() => { });
-                }
+                //    manifest no longer references them) — inside an owner-
+                //    sanctioned retirement window (ADR-004 §7): compaction is the
+                //    ONE legitimate deleter of graph-lsm members, so the family is
+                //    unregistered around exactly this loop and re-registered in a
+                //    finally (self-healing: every init re-declares). Failures stay
+                //    harmless — the worst outcome is leaked disk space.
+                await withFamilyRetirement(this.storage, GRAPH_FAMILIES[0], async () => {
+                    await Promise.all(result.oldIds.map((oldId) => {
+                        const oldBlobKey = this.blobKey(treeName, oldId);
+                        return this.storage
+                            .deleteBinaryBlob(oldBlobKey)
+                            .catch(() => {
+                            /* Orphaned blobs acceptable */
+                        });
+                    }));
+                });
                 const elapsed = Date.now() - startTime;
                 prodLog.info(`GraphAdjacencyIndex: Compaction ${treeName} L${level} → L${result.newLevel} complete in ${elapsed}ms`);
                 if (result.newLevel < 6 && this.native.needsCompaction(treeName, result.newLevel)) {

package/dist/hnsw/NativeDiskAnnWrapper.d.ts

@@ -70,7 +70,7 @@
  * brainy 8.0's canonical `'vector'` provider key. Whenever cor is
  * installed, brainy's vector index slot resolves to Adaptive DiskANN.
  */
-import type { Vector, VectorDocument, DistanceFunction, StorageAdapter } from '@soulcraft/brainy';
+import type { Vector, VectorDocument, DistanceFunction, StorageAdapter, ProviderInvariantReport } from '@soulcraft/brainy';
 import type { VectorIndexProvider } from '../providerContracts.js';
 import type { EntityIdMapperLike } from '../utils/columnStoreTypes.js';
 import type { MigrationCoordinator, MigrationStatus } from '../migration/MigrationCoordinator.js';
@@ -237,6 +237,14 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
      * index. Set in {@link tryOpenExisting}; cleared by a successful rebuild.
      */
     private durableBaseLoadFailed;
+    /**
+     * L0 segments named by the persisted manifest that FAILED to load at
+     * cold open (skipped with a warn; entries remain in canonical and heal
+     * via consolidation). Feeds the ADR-004 §6 `segments-resident`
+     * invariant so the deliberately-tolerated gap is VISIBLE cross-layer
+     * instead of only a boot-time warn line.
+     */
+    private skippedManifestSegments;
     /** Serializes manifest writes: the storage adapter has no per-key write
      * ordering, so two in-flight saves (a flush racing a consolidation) could
      * physically land out of order and persist a STALE segment list — losing a
@@ -377,6 +385,14 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
      * (see {@link loadSegmentManifest}).
      * @returns `true` when a cold-open rebuild would be redundant.
      */
+    /**
+     * ADR-004 §6 — the vector provider's invariant self-report. NEVER
+     * throws; bounded (flags + fault-discriminating stats on ≤257 sidecar
+     * paths — the L0 hard cap bounds the loop). `heal: 'rebuild'` maps to
+     * {@link rebuild}; the skipped-segment gap is deliberately
+     * consolidation-healed and reports `heal: 'none'`.
+     */
+    validateInvariants(): Promise<ProviderInvariantReport>;
     isReady(): boolean;
     /**
      * @description **#18 migration lock — structured progress** Brainy relays into
@@ -504,6 +520,30 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
     private flushDeltaToL0;
     /** The flush body — see {@link flushDeltaToL0}. */
     private runFlushToL0;
+    /**
+     * ADR-004 §7 — verify the `main.familygen` stamp the native publish
+     * writes (3.0.16+). The stamp commits the base + sidecar SET with each
+     * member's exact byte size; a member missing or at the wrong size means
+     * the family on disk is torn (interrupted swap or external mutation)
+     * and must NOT be served. Stamp absence is a pre-stamp layout — legacy
+     * per-file tolerance applies. A read/stat FAULT is `unverifiable`, never
+     * conflated with absence (§4): we proceed on the per-file checks and
+     * report it, but never trigger a spurious rebuild from a flaky probe.
+     */
+    /**
+     * Sibling path with the LAST extension swapped — the exact semantics of
+     * Rust's `Path::set_extension`, which names every family member. This
+     * MUST NOT assume the base ends in `.dkann`: production indexPaths come
+     * from `getBinaryBlobPath` and FileSystemStorage appends `.bin`
+     * (`main.dkann.bin`), so the sidecars/stamp are `main.dkann.slotmap` /
+     * `main.dkann.familygen` there, while bare `main.dkann` paths (tests,
+     * benchmarks) yield `main.slotmap` / `main.familygen`. A `.dkann`-only
+     * regex silently no-ops on the production shape — the 3.0.16 gate
+     * caught the stamp verifier READING THE BINARY BASE as its own stamp
+     * (incoherent verdict on every healthy brain ⇒ rebuild loop).
+     */
+    private siblingPath;
+    private verifyFamilyStamp;
     private tryOpenExisting;
     /**
      * Remove any leftover `main.slots.json` written by a pre-#72 RC build.

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -70,10 +70,13 @@
  * brainy 8.0's canonical `'vector'` provider key. Whenever cor is
  * installed, brainy's vector index slot resolves to Adaptive DiskANN.
  */
+import { composeInvariantReport } from '../utils/invariantReport.js';
+import { declareDerivedFamilies, VECTOR_FAMILIES } from '../utils/derivedFamilies.js';
+import { statSync, readFileSync } from 'node:fs';
 import { loadNativeModule } from '../native/index.js';
 import { prodLog } from '@soulcraft/brainy/internals';
 import { mkdirSync, existsSync, rmSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { autoModeForHeader, selectModeFromResourceManager, } from './AdaptiveDiskAnnModeSelector.js';
 /**
  * Node-count threshold above which `useMmapAdjacency: 'auto'`
@@ -374,6 +377,14 @@ export class NativeDiskAnnWrapper {
      * index. Set in {@link tryOpenExisting}; cleared by a successful rebuild.
      */
     durableBaseLoadFailed = false;
+    /**
+     * L0 segments named by the persisted manifest that FAILED to load at
+     * cold open (skipped with a warn; entries remain in canonical and heal
+     * via consolidation). Feeds the ADR-004 §6 `segments-resident`
+     * invariant so the deliberately-tolerated gap is VISIBLE cross-layer
+     * instead of only a boot-time warn line.
+     */
+    skippedManifestSegments = [];
     /** Serializes manifest writes: the storage adapter has no per-key write
      * ordering, so two in-flight saves (a flush racing a consolidation) could
      * physically land out of order and persist a STALE segment list — losing a
@@ -851,6 +862,126 @@ export class NativeDiskAnnWrapper {
      * (see {@link loadSegmentManifest}).
      * @returns `true` when a cold-open rebuild would be redundant.
      */
+    /**
+     * ADR-004 §6 — the vector provider's invariant self-report. NEVER
+     * throws; bounded (flags + fault-discriminating stats on ≤257 sidecar
+     * paths — the L0 hard cap bounds the loop). `heal: 'rebuild'` maps to
+     * {@link rebuild}; the skipped-segment gap is deliberately
+     * consolidation-healed and reports `heal: 'none'`.
+     */
+    async validateInvariants() {
+        return composeInvariantReport('vector', () => this.isReady(), [
+            () => ({
+                name: 'base-resident',
+                holds: !this.durableBaseLoadFailed,
+                detail: this.durableBaseLoadFailed
+                    ? 'a durable base index exists but failed to load (corrupt base or missing sidecar) — searches would silently miss its vectors'
+                    : 'durable base (if any) loaded',
+                heal: 'rebuild',
+            }),
+            () => ({
+                name: 'segments-resident',
+                holds: this.skippedManifestSegments.length === 0,
+                detail: this.skippedManifestSegments.length === 0
+                    ? `${this.l0Segments.length} manifest-named L0 segment(s), all loaded`
+                    : `${this.skippedManifestSegments.length} manifest-named L0 segment(s) ` +
+                        `failed to load (${this.skippedManifestSegments.join(', ')}) — their ` +
+                        `entries remain in canonical and heal via consolidation`,
+                expected: this.l0Segments.length + this.skippedManifestSegments.length,
+                actual: this.l0Segments.length,
+                heal: 'none',
+            }),
+            () => {
+                // sidecars-coherent: base + every loaded segment has both sidecars.
+                // Fault-discriminating stat (ADR §4): a stat FAULT is reported as a
+                // failing check, never as absence.
+                const missing = [];
+                const faulted = [];
+                const probe = (path) => {
+                    try {
+                        statSync(path);
+                    }
+                    catch (error) {
+                        const code = error.code;
+                        if (code === 'ENOENT')
+                            missing.push(path);
+                        else
+                            faulted.push(`${path} (${code})`);
+                    }
+                };
+                // Last-extension swap (Rust set_extension semantics) — a
+                // .dkann-only regex no-ops on production's `.dkann.bin` paths and
+                // made this check vacuously probe the base file twice.
+                const sidecarsOf = (dkannPath) => [
+                    this.siblingPath(dkannPath, 'slotmap'),
+                    this.siblingPath(dkannPath, 'slotrev'),
+                ];
+                if (this.native && this.config.indexPath) {
+                    for (const s of sidecarsOf(this.config.indexPath))
+                        probe(s);
+                }
+                for (const seg of this.l0Segments) {
+                    for (const s of sidecarsOf(this.segPath(seg.file)))
+                        probe(s);
+                }
+                if (faulted.length > 0) {
+                    return {
+                        name: 'sidecars-coherent',
+                        holds: false,
+                        detail: `sidecar stat FAULTED (not absent) — coherence unverifiable: ${faulted.join(', ')}`,
+                        heal: 'none',
+                    };
+                }
+                return {
+                    name: 'sidecars-coherent',
+                    holds: missing.length === 0,
+                    detail: missing.length === 0
+                        ? 'every loaded base/segment has both sidecars on disk'
+                        : `${missing.length} sidecar(s) missing for LOADED members: ${missing.join(', ')} — ` +
+                            `the family is incoherent on disk (a restart would fail these loads)`,
+                    heal: 'rebuild',
+                };
+            },
+            () => {
+                // family-coherent (§7): the familygen stamp — when the 3.0.16+
+                // publish wrote one — must find every member it committed at its
+                // EXACT byte size, live on disk. Absence is a pre-stamp layout,
+                // not a violation; a stat/read fault is unverifiable (heal
+                // 'none' — a flaky probe never triggers a spurious rebuild).
+                const family = this.verifyFamilyStamp();
+                switch (family.state) {
+                    case 'coherent':
+                        return {
+                            name: 'family-coherent',
+                            holds: true,
+                            detail: `familygen stamp verified — every member at its committed size (generation ${family.generation})`,
+                            heal: 'rebuild',
+                        };
+                    case 'absent':
+                        return {
+                            name: 'family-coherent',
+                            holds: true,
+                            detail: 'no familygen stamp (pre-3.0.16 publish) — per-file checks apply',
+                            heal: 'rebuild',
+                        };
+                    case 'unverifiable':
+                        return {
+                            name: 'family-coherent',
+                            holds: false,
+                            detail: `family coherence UNVERIFIABLE: ${family.violations.join('; ')}`,
+                            heal: 'none',
+                        };
+                    case 'incoherent':
+                        return {
+                            name: 'family-coherent',
+                            holds: false,
+                            detail: `familygen stamp violated — the family on disk is torn: ${family.violations.join('; ')}`,
+                            heal: 'rebuild',
+                        };
+                }
+            },
+        ]);
+    }
     isReady() {
         if (this.durableBaseLoadFailed)
             return false;
@@ -1355,6 +1486,9 @@ export class NativeDiskAnnWrapper {
      * still gets the segments lazily; only the pre-gate timing needs init().)
      */
     async init() {
+        // ADR-004 §7: declare the vector families (feature-detected ≥8.3.0;
+        // idempotent; loud-but-non-blocking).
+        await declareDerivedFamilies(this.storage, VECTOR_FAMILIES);
         await this.ensureSegments();
     }
     /** Memoized segment-manifest cold-load (+ canonical-coverage probe). */
@@ -1431,6 +1565,7 @@ export class NativeDiskAnnWrapper {
         }
         if (!manifest)
             return;
+        this.skippedManifestSegments = [];
         this.manifestNextId = Math.max(1, Number(manifest.nextId) || 1);
         const bindings = loadNativeModule();
         const NativeDiskANN = bindings.NativeDiskAnn;
@@ -1444,6 +1579,7 @@ export class NativeDiskAnnWrapper {
                 this.l0Segments.push({ ...entry, native });
             }
             catch (error) {
+                this.skippedManifestSegments.push(entry.file);
                 prodLog.warn(`NativeDiskAnnWrapper: skipping unreadable L0 segment ${entry.file} ` +
                     `(${error instanceof Error ? error.message : String(error)}) — its ` +
                     `entries remain in canonical storage; consolidation heals the set`);
@@ -1592,7 +1728,107 @@ export class NativeDiskAnnWrapper {
             });
         }
     }
+    /**
+     * ADR-004 §7 — verify the `main.familygen` stamp the native publish
+     * writes (3.0.16+). The stamp commits the base + sidecar SET with each
+     * member's exact byte size; a member missing or at the wrong size means
+     * the family on disk is torn (interrupted swap or external mutation)
+     * and must NOT be served. Stamp absence is a pre-stamp layout — legacy
+     * per-file tolerance applies. A read/stat FAULT is `unverifiable`, never
+     * conflated with absence (§4): we proceed on the per-file checks and
+     * report it, but never trigger a spurious rebuild from a flaky probe.
+     */
+    /**
+     * Sibling path with the LAST extension swapped — the exact semantics of
+     * Rust's `Path::set_extension`, which names every family member. This
+     * MUST NOT assume the base ends in `.dkann`: production indexPaths come
+     * from `getBinaryBlobPath` and FileSystemStorage appends `.bin`
+     * (`main.dkann.bin`), so the sidecars/stamp are `main.dkann.slotmap` /
+     * `main.dkann.familygen` there, while bare `main.dkann` paths (tests,
+     * benchmarks) yield `main.slotmap` / `main.familygen`. A `.dkann`-only
+     * regex silently no-ops on the production shape — the 3.0.16 gate
+     * caught the stamp verifier READING THE BINARY BASE as its own stamp
+     * (incoherent verdict on every healthy brain ⇒ rebuild loop).
+     */
+    siblingPath(indexPath, ext) {
+        return indexPath.replace(/\.[^./\\]+$/, `.${ext}`);
+    }
+    verifyFamilyStamp() {
+        const indexPath = this.config.indexPath;
+        if (!indexPath)
+            return { state: 'absent' };
+        const stampPath = this.siblingPath(indexPath, 'familygen');
+        let raw;
+        try {
+            raw = readFileSync(stampPath, 'utf8');
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT')
+                return { state: 'absent' };
+            return {
+                state: 'unverifiable',
+                violations: [`stamp read FAULTED (${code}) — coherence unverifiable`],
+            };
+        }
+        let stamp;
+        try {
+            stamp = JSON.parse(raw);
+        }
+        catch {
+            return {
+                state: 'incoherent',
+                violations: [`stamp ${stampPath} present but unparseable — cannot prove family coherence`],
+            };
+        }
+        if (typeof stamp?.members !== 'object' || stamp.members === null) {
+            return {
+                state: 'incoherent',
+                violations: [`stamp ${stampPath} has no members map — cannot prove family coherence`],
+            };
+        }
+        const dir = dirname(indexPath);
+        const violations = [];
+        const faults = [];
+        for (const [name, expected] of Object.entries(stamp.members)) {
+            try {
+                const actual = statSync(join(dir, name)).size;
+                if (actual !== expected) {
+                    violations.push(`${name}: size ${actual} != committed ${expected}`);
+                }
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'ENOENT') {
+                    violations.push(`${name}: missing (committed ${expected} bytes)`);
+                }
+                else {
+                    faults.push(`${name}: stat FAULTED (${code})`);
+                }
+            }
+        }
+        if (violations.length > 0)
+            return { state: 'incoherent', violations };
+        if (faults.length > 0)
+            return { state: 'unverifiable', violations: faults };
+        return { state: 'coherent', generation: stamp.generation ?? 0 };
+    }
     tryOpenExisting() {
+        // §7: an incoherent family must not be served — refuse before the
+        // open so a torn set reads as a FAILED durable load (not-ready ⇒
+        // brainy's gate rebuilds), never as a quietly-wrong index.
+        const family = this.verifyFamilyStamp();
+        if (family.state === 'incoherent') {
+            prodLog.error(`NativeDiskAnnWrapper: familygen stamp says the vector family is ` +
+                `INCOHERENT — refusing to open. ${family.violations.join('; ')}`);
+            this.native = null;
+            this.durableBaseLoadFailed = true;
+            return;
+        }
+        if (family.state === 'unverifiable') {
+            prodLog.error(`NativeDiskAnnWrapper: family coherence UNVERIFIABLE (stat/read fault) — ` +
+                `opening on per-file checks only. ${family.violations.join('; ')}`);
+        }
         try {
             const bindings = loadNativeModule();
             // napi-rs exports the class as `NativeDiskAnn` (PascalCase
@@ -1664,7 +1900,20 @@ export class NativeDiskAnnWrapper {
      */
     removeLegacySlotsSidecar() {
         try {
-            const legacy = this.config.indexPath.replace(/\.dkann$/, '.slots.json');
+            // THE DELETER (CORTEX-BLOB-LIFECYCLE-CONTRACT, identified 2026-07-13
+            // by the §7 family-coherent gate): this derivation was a
+            // `.dkann$`-anchored replace, which NO-OPS on production paths
+            // (getBinaryBlobPath appends `.bin` → `main.dkann.bin`) — so
+            // `legacy === indexPath` and every successful cold open DELETED THE
+            // BASE INDEX it had just mmap-opened. The live inode kept serving,
+            // the next open found no base, and the brain rebuilt — the exact
+            // main.dkann-missing/sidecars-present signature on all four
+            // memory-vm brains. Last-extension swap + a hard never-the-base
+            // guard make the recurrence structurally impossible.
+            const indexPath = this.config.indexPath;
+            const legacy = this.siblingPath(indexPath, 'slots.json');
+            if (legacy === indexPath)
+                return;
             if (existsSync(legacy))
                 rmSync(legacy, { force: true });
         }

package/dist/native/types.d.ts

@@ -923,6 +923,13 @@ export interface NativeMetadataIndexInstance {
     uuidToInt(uuid: string): number | null;
     intToUuid(intId: number): string | null;
     intsToUuids(ints: number[]): string[];
+    /**
+     * Resolve an entity int, ASSIGNING through the canonical allocator when
+     * unmapped (3.0.16+; the same allocator addToIndex uses, durable via the
+     * mapper's delta log). Lets a boot-heal vector rebuild mint ids for
+     * canonical-committed entities whose index ops were lost.
+     */
+    getOrAssignInt(uuid: string): bigint;
     loadFieldRegistry(json: string): void;
     saveFieldRegistry(): string;
     loadFieldIndex(field: string, json: string): void;

package/dist/utils/NativeColumnStore.d.ts

@@ -30,6 +30,7 @@
  * `.cidx` segment value types and ordering. See ADR-001 for the native string
  * collation contract (code-point order, matching `compareCodePoints`).
  */
+import type { ProviderInvariantReport } from '@soulcraft/brainy';
 import type { StorageAdapter } from '@soulcraft/brainy';
 import type { ColumnStoreProvider, EntityIdMapperLike } from './columnStoreTypes.js';
 import { ValueType } from './columnStoreTypes.js';
@@ -142,6 +143,11 @@ export declare class NativeColumnStore implements ColumnStoreProvider {
      * 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).
+     */
+    validateInvariants(): Promise<ProviderInvariantReport>;
     private assertFieldServable;
     /**
      * @description Point filter: entity int ids whose `field` equals `value`.

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