@soulcraft/cor 3.0.18 → 3.0.19

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -86,6 +86,14 @@ export declare class GraphAdjacencyIndex implements GraphIndexProvider {
      */
     private canonicalUnindexed;
     private isRebuilding;
+    /** Membership mutated since the last persisted blob (write-side dirty bit). */
+    private membershipDirty;
+    /** Cached stamp content (minus committedAt) — identical payload = no I/O on idle ticks. */
+    private lastMembershipStampBody;
+    /** Byte length of the last persisted membership blob (stamp needs it without re-serializing). */
+    private lastMembershipBlobBytes;
+    /** How this boot obtained membership: restored (stamp), healed (walk), or fresh (no verbs). */
+    private membershipBootState;
     private flushTimer?;
     private rebuildStartTime;
     private totalRelationshipsIndexed;
@@ -174,6 +182,32 @@ export declare class GraphAdjacencyIndex implements GraphIndexProvider {
      * queryable edges report "not ready".
      */
     private openGraphLsmEngine;
+    /**
+     * SHA-256 over the tree's durable SSTable identity (sorted `id:level`
+     * lines). The stamp records one per tree; a mismatch at open means the
+     * trees advanced (or tore) after the last membership persist, so the
+     * blob cannot be trusted and the walk heals. Content-relevant fields
+     * only — deliberately NOT the raw manifest JSON (timestamps and field
+     * ordering must not fail coherence).
+     */
+    private treeFingerprint;
+    /**
+     * Persist the membership family: blob (only when membership mutated or
+     * `force`) then stamp LAST (§7 — the stamp commits the set). Identical
+     * stamp payloads are skipped entirely, so idle auto-flush ticks cost
+     * zero I/O. Failures log loudly and leave the previous stamp in place —
+     * a stale stamp heals at next open; a silent half-persist would not.
+     */
+    private persistVerbMembership;
+    /**
+     * Restore membership from the stamped blob. Returns `true` only when the
+     * FULL coherence chain holds: stamp present → blob present with the exact
+     * stamped byte length → every tree fingerprint matches the durable state
+     * just loaded → the native parser accepts every framed section. Any break
+     * returns `false` (absent stamp silently — that is every pre-3.0.19
+     * brain; a broken chain with a warn) and the caller's walk heals.
+     */
+    private loadVerbMembershipFromStorage;
     private populateVerbIdSetFromStorage;
     getNeighbors(id: bigint, optionsOrDirection?: {
         direction?: 'in' | 'out' | 'both';

package/dist/graph/NativeGraphAdjacencyIndex.js

@@ -13,6 +13,7 @@
  * since it coordinates cross-subsystem caching and requires async storage access.
  */
 import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
 import { TypeUtils, VerbType } from '@soulcraft/brainy/types/graphTypes';
 import { loadNativeModule } from '../native/index.js';
 import { composeInvariantReport } from '../utils/invariantReport.js';
@@ -45,6 +46,18 @@ const VERB_FALLBACK_INDEX = TypeUtils.getVerbIndex(VerbType.RelatedTo) ?? 3;
  * (`verb-uuid-to-int.mkv`, `verb-int-to-uuid.bin`, `verb-endpoints/`).
  */
 const GRAPH_VERB_NS_PROBE_KEY = '_graph_verb_ns/x';
+/**
+ * Persisted verb-membership family (3.0.19). The roster / per-type unions /
+ * per-(type, subtype) buckets / count families were RAM-only, costing every
+ * boot of every verb-bearing brain an O(all-canonical-verbs) walk and
+ * silently emptying subtype-filtered traversal after restarts. The blob is
+ * the serialized structures; the stamp ties the blob to the exact durable
+ * tree state (per-tree SSTable fingerprints) so a torn write is DETECTED at
+ * open and heals via the walk — §7 coherent-or-rebuild, same discipline as
+ * the vector family.
+ */
+const GRAPH_MEMBERSHIP_BLOB_KEY = 'graph-verb-membership';
+const GRAPH_MEMBERSHIP_STAMP_KEY = 'graph-membership-stamp';
 /**
  * Resolve a verb-type string to its canonical `VerbTypeEnum` index,
  * falling back to {@link VERB_FALLBACK_INDEX} (`VerbType.RelatedTo`)
@@ -91,6 +104,14 @@ export class GraphAdjacencyIndex {
      */
     canonicalUnindexed = false;
     isRebuilding = false;
+    /** Membership mutated since the last persisted blob (write-side dirty bit). */
+    membershipDirty = false;
+    /** Cached stamp content (minus committedAt) — identical payload = no I/O on idle ticks. */
+    lastMembershipStampBody = '';
+    /** Byte length of the last persisted membership blob (stamp needs it without re-serializing). */
+    lastMembershipBlobBytes = -1;
+    /** How this boot obtained membership: restored (stamp), healed (walk), or fresh (no verbs). */
+    membershipBootState = 'fresh';
     flushTimer;
     rebuildStartTime = 0;
     totalRelationshipsIndexed = 0;
@@ -293,13 +314,126 @@ export class GraphAdjacencyIndex {
         for (const treeName of treeNames) {
             await this.loadTreeFromStorage(treeName);
         }
+        // Persisted-membership restore (3.0.19): coherent stamp + blob loads the
+        // roster/buckets/counts in O(bitmap) — no canonical walk, subtype filters
+        // intact. `restored` also covers the legitimately-empty-roster case (all
+        // verbs removed) so the walk below can't re-fire on it every boot.
+        const restored = await this.loadVerbMembershipFromStorage();
         // Defensive check: if LSM-trees have data but verbIdSet is empty, populate.
-        // This is the deferred membership fast-follow — it does NOT gate isReady().
+        // This is the membership HEAL path (pre-3.0.19 brains, torn/missing
+        // stamp) — it does NOT gate isReady().
         const sourceSize = this.native.size();
-        if (sourceSize > 0 && this.native.verbIdCount() === 0) {
+        if (!restored && sourceSize > 0 && this.native.verbIdCount() === 0) {
             prodLog.warn(`GraphAdjacencyIndex: LSM-trees have ${sourceSize} relationships but verbIdSet is empty. ` +
                 `Triggering auto-rebuild to restore consistency.`);
             await this.populateVerbIdSetFromStorage();
+            this.membershipBootState = 'healed';
+            // Persist immediately so the NEXT boot restores instead of re-walking.
+            await this.persistVerbMembership(true);
+        }
+        else if (!restored && this.native.verbIdCount() > 0) {
+            // Verbs arrived without a stamp (e.g. mid-process rebuild) — treat as
+            // healed so the invariant reports honestly.
+            this.membershipBootState = 'healed';
+        }
+    }
+    /**
+     * SHA-256 over the tree's durable SSTable identity (sorted `id:level`
+     * lines). The stamp records one per tree; a mismatch at open means the
+     * trees advanced (or tore) after the last membership persist, so the
+     * blob cannot be trusted and the walk heals. Content-relevant fields
+     * only — deliberately NOT the raw manifest JSON (timestamps and field
+     * ordering must not fail coherence).
+     */
+    treeFingerprint(treeName) {
+        const ids = this.native.getManifestSstableIds(treeName);
+        const lines = ids
+            .map((id) => `${id}:${this.native.getManifestSstableLevel(treeName, id) ?? '?'}`)
+            .sort();
+        return createHash('sha256').update(lines.join('\n')).digest('hex');
+    }
+    /**
+     * Persist the membership family: blob (only when membership mutated or
+     * `force`) then stamp LAST (§7 — the stamp commits the set). Identical
+     * stamp payloads are skipped entirely, so idle auto-flush ticks cost
+     * zero I/O. Failures log loudly and leave the previous stamp in place —
+     * a stale stamp heals at next open; a silent half-persist would not.
+     */
+    async persistVerbMembership(force = false) {
+        if (!this.hasBinaryBlobs)
+            return;
+        try {
+            if (this.membershipDirty || force || this.lastMembershipBlobBytes < 0) {
+                const blob = this.native.serializeVerbMembership();
+                await this.storage.saveBinaryBlob(GRAPH_MEMBERSHIP_BLOB_KEY, Buffer.from(blob));
+                this.lastMembershipBlobBytes = blob.length;
+                this.membershipDirty = false;
+            }
+            const trees = {};
+            for (const treeName of this.native.treeNames()) {
+                trees[treeName] = this.treeFingerprint(treeName);
+            }
+            const body = JSON.stringify({ v: 1, blobBytes: this.lastMembershipBlobBytes, trees });
+            if (body === this.lastMembershipStampBody)
+                return;
+            const stamp = {
+                v: 1,
+                committedAt: Date.now(),
+                blobBytes: this.lastMembershipBlobBytes,
+                trees,
+            };
+            await this.storage.saveMetadata(GRAPH_MEMBERSHIP_STAMP_KEY, {
+                noun: 'thing',
+                data: stamp,
+            });
+            this.lastMembershipStampBody = body;
+        }
+        catch (error) {
+            prodLog.error('GraphAdjacencyIndex: failed to persist verb membership — next open will heal via the canonical walk', error);
+        }
+    }
+    /**
+     * Restore membership from the stamped blob. Returns `true` only when the
+     * FULL coherence chain holds: stamp present → blob present with the exact
+     * stamped byte length → every tree fingerprint matches the durable state
+     * just loaded → the native parser accepts every framed section. Any break
+     * returns `false` (absent stamp silently — that is every pre-3.0.19
+     * brain; a broken chain with a warn) and the caller's walk heals.
+     */
+    async loadVerbMembershipFromStorage() {
+        if (!this.hasBinaryBlobs)
+            return false;
+        try {
+            const meta = await this.storage.getMetadata(GRAPH_MEMBERSHIP_STAMP_KEY);
+            const stamp = meta?.data;
+            if (!stamp || stamp.v !== 1)
+                return false;
+            const blob = await this.storage.loadBinaryBlob(GRAPH_MEMBERSHIP_BLOB_KEY);
+            if (!blob || blob.length !== stamp.blobBytes) {
+                prodLog.warn(`GraphAdjacencyIndex: membership blob ${blob ? `is ${blob.length} bytes but the stamp committed ${stamp.blobBytes}` : 'is MISSING under a present stamp'} — healing via the canonical walk`);
+                return false;
+            }
+            for (const treeName of this.native.treeNames()) {
+                const now = this.treeFingerprint(treeName);
+                if (stamp.trees?.[treeName] !== now) {
+                    prodLog.warn(`GraphAdjacencyIndex: membership stamp is stale for tree '${treeName}' (durable SSTables changed after the last persist) — healing via the canonical walk`);
+                    return false;
+                }
+            }
+            this.native.loadVerbMembership(blob);
+            this.lastMembershipBlobBytes = blob.length;
+            this.lastMembershipStampBody = JSON.stringify({
+                v: 1,
+                blobBytes: stamp.blobBytes,
+                trees: stamp.trees,
+            });
+            this.membershipBootState = 'restored';
+            prodLog.info(`GraphAdjacencyIndex: verb membership restored from stamp (${this.native.verbIdCount()} live verbs, no canonical walk)`);
+            return true;
+        }
+        catch (error) {
+            prodLog.warn('GraphAdjacencyIndex: membership restore failed — healing via the canonical walk', error);
+            return false;
         }
     }
     async populateVerbIdSetFromStorage() {
@@ -313,12 +447,16 @@ export class GraphAdjacencyIndex {
                 pagination: { limit: 10000, cursor }
             });
             for (const verb of result.items) {
-                // Cor 3.0 Piece D: trackVerbIdByIndex was deleted along with
-                // the other strict-index variants. trackVerbId takes the verb-
-                // type as a string; unknown strings fall back to RelatedTo —
-                // acceptable on the rebuild slow path because the membership
-                // bitmap converges to the same set either way.
-                this.native.trackVerbId(verb.id, verb.verb);
+                // Full-fidelity tracking (3.0.19): the membership-only walk used
+                // to drop subtype state, silently emptying findConnectedSubtype
+                // after every restart. Canonical carries the subtype (brainy
+                // 7.30.0+) — a METADATA field on verbs, surfaced top-level on
+                // hydrated items; read both shapes. Unknown type strings fall
+                // back to RelatedTo — acceptable on the rebuild slow path
+                // because the membership bitmap converges either way.
+                const v = verb;
+                const subtype = v.subtype ?? v.metadata?.subtype ?? '';
+                this.native.trackVerbIdFull(verb.id, resolveVerbTypeIndex(verb.verb), subtype);
                 count++;
             }
             hasMore = result.hasMore;
@@ -437,6 +575,7 @@ export class GraphAdjacencyIndex {
         // coalesce absent subtype to '' here.
         const subtype = verb.subtype ?? '';
         const result = this.native.addVerbWithEndpointsByIndex(verb.id, sourceInt, targetInt, verbTypeIndex, subtype, generation);
+        this.membershipDirty = true;
         // Flush any trees that hit their threshold
         const flushPromises = [];
         if (result.needsFlushSource) {
@@ -465,8 +604,19 @@ export class GraphAdjacencyIndex {
         await this.ensureInitialized();
         // Load verb to get type + subtype info
         const verb = await this.getVerbCached(verbId);
-        if (!verb)
+        if (!verb) {
+            // REMOVAL LAW (3.0.19): removal must never require reading the thing
+            // being removed. A ghost verb (canonical row unreadable) used to be
+            // silently SKIPPED here — its graph rows survived forever, the exact
+            // shape of brainy's replace-path defect one layer down. The id-only
+            // native path resolves type/subtype from cor-owned state instead.
+            const removed = this.native.removeVerbByIdOnly(verbId, generation);
+            if (removed) {
+                this.membershipDirty = true;
+                prodLog.warn(`GraphAdjacencyIndex: removed ghost verb ${verbId} via the id-only path (canonical row unreadable — removal law)`);
+            }
             return;
+        }
         const startTime = performance.now();
         const verbTypeIndex = resolveVerbTypeIndex(verb.verb);
         // Native subtype param is `String` with '' = "no subtype" (the empty-string
@@ -475,6 +625,7 @@ export class GraphAdjacencyIndex {
         // coalesce absent subtype to '' here.
         const subtype = verb.subtype ?? '';
         this.native.removeVerb(verbId, verbTypeIndex, subtype, generation);
+        this.membershipDirty = true;
         const elapsed = performance.now() - startTime;
         if (elapsed > 5.0) {
             prodLog.warn(`GraphAdjacencyIndex: Slow removeVerb for ${verbId}: ${elapsed.toFixed(2)}ms`);
@@ -600,6 +751,19 @@ export class GraphAdjacencyIndex {
                     : 'no canonical-vs-durable coverage gap detected',
                 heal: 'rebuild',
             }),
+            () => ({
+                name: 'membership-stamp',
+                // Every boot path lands in an honest state: restored (stamp
+                // coherent), healed (walk ran — first boot on 3.0.19, or a torn
+                // stamp), or fresh (no verbs anywhere). A verb-bearing graph
+                // whose membership is EMPTY while trees hold edges is the only
+                // failing shape — subtype filters would silently serve nothing.
+                holds: !(this.native.size() > 0 && this.native.verbIdCount() === 0),
+                detail: this.native.size() > 0 && this.native.verbIdCount() === 0
+                    ? 'trees hold edges but the live-verb roster is EMPTY — membership restore AND heal both failed'
+                    : `membership ${this.membershipBootState} this boot (${this.native.verbIdCount()} live verbs)`,
+                heal: 'rebuild',
+            }),
         ]);
     }
     isReady() {
@@ -719,8 +883,18 @@ export class GraphAdjacencyIndex {
                 for (const verb of result.items) {
                     totalVerbs++;
                     const verbType = verb.verb ?? 'relatedTo';
+                    const verbTypeIndex = resolveVerbTypeIndex(verbType);
+                    // Native subtype param is `String` with '' = "no subtype" (the
+                    // empty-string escape; graph_adjacency.rs guards on
+                    // `!subtype.is_empty()`). JS null throws "Null into String" at the
+                    // napi boundary, so coalesce absent subtype to ''. Subtype is a
+                    // metadata field on verbs — read both hydration shapes.
+                    const vv = verb;
+                    const subtype = vv.subtype ?? vv.metadata?.subtype ?? '';
                     if (!reconstructAdjacency) {
-                        this.native.trackVerbId(verb.id, verbType);
+                        // Full-fidelity membership (3.0.19): subtype rides the walk so
+                        // filtered traversal survives the rebuild.
+                        this.native.trackVerbIdFull(verb.id, verbTypeIndex, subtype);
                         continue;
                     }
                     const sourceId = verb.sourceId;
@@ -730,16 +904,10 @@ export class GraphAdjacencyIndex {
                     if (sourceInt === undefined || targetInt === undefined) {
                         // Endpoint not in the mapper — still record membership so the verb
                         // isn't lost; its adjacency can't be rebuilt without the int.
-                        this.native.trackVerbId(verb.id, verbType);
+                        this.native.trackVerbIdFull(verb.id, verbTypeIndex, subtype);
                         unresolvedEndpoints++;
                         continue;
                     }
-                    const verbTypeIndex = resolveVerbTypeIndex(verbType);
-                    // Native subtype param is `String` with '' = "no subtype" (the
-                    // empty-string escape; graph_adjacency.rs guards on
-                    // `!subtype.is_empty()`). JS null throws "Null into String" at the
-                    // napi boundary, so coalesce absent subtype to ''.
-                    const subtype = verb.subtype ?? '';
                     const addResult = this.native.addVerbWithEndpointsByIndex(verb.id, BigInt(sourceInt), BigInt(targetInt), verbTypeIndex, subtype, REBUILD_GENERATION);
                     edgesRebuilt++;
                     // Respect memtable flush thresholds mid-walk so RAM stays bounded.
@@ -759,6 +927,15 @@ export class GraphAdjacencyIndex {
                 cursor = result.nextCursor;
             }
             this.totalRelationshipsIndexed = totalVerbs;
+            // The walk rebuilt membership through the native handle directly (the
+            // wrapper's dirty bit never fired) — mark it so the persist below and
+            // any later flush write the fresh blob.
+            this.membershipDirty = true;
+            if (!reconstructAdjacency) {
+                // Membership-only rebuild writes no memtables, so no flush runs —
+                // persist the family directly or the walk repeats next boot.
+                await this.persistVerbMembership(true);
+            }
             if (reconstructAdjacency) {
                 // Persist partially-filled memtables from the final batch.
                 await this.flush();
@@ -800,6 +977,9 @@ export class GraphAdjacencyIndex {
         if (flushPromises.length > 0) {
             await Promise.all(flushPromises);
         }
+        // Membership family rides every flush cycle: blob only when membership
+        // mutated, stamp only when the payload changed — idle ticks cost nothing.
+        await this.persistVerbMembership();
         const elapsed = Date.now() - startTime;
         prodLog.debug(`GraphAdjacencyIndex: Flush completed in ${elapsed}ms`);
     }
@@ -1031,6 +1211,11 @@ export class GraphAdjacencyIndex {
                         });
                     }));
                 });
+                // Compaction changed the durable SSTable identity, so the
+                // membership stamp's fingerprint for this tree is now stale —
+                // refresh it (stamp-only unless membership also mutated). Without
+                // this, the next open would needlessly heal via the walk.
+                await this.persistVerbMembership();
                 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

@@ -458,6 +458,17 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
     getPersistMode(): 'immediate' | 'deferred';
     /** Absolute path of a segment file (lives next to the base indexPath). */
     private segPath;
+    /**
+     * Move poisoned L0 segments out of the live set into
+     * `<indexDir>/quarantine/` — preserved for forensics, NEVER deleted
+     * (accord's 545 poisoned segments were the evidence that convicted the
+     * June dim bug). Crash-safe order: the manifest stops referencing the
+     * segments FIRST (a crash after that leaves orphaned, de-referenced
+     * files — a harmless leak), then the files move. The dropped native
+     * handles close with their references; nothing reads a de-referenced
+     * segment.
+     */
+    private quarantineSegments;
     /** Membership across the base + every L0 segment (int → any slot). */
     private hasIntAnywhere;
     /**

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -75,8 +75,8 @@ import { declareDerivedFamilies, VECTOR_FAMILIES } from '../utils/derivedFamilie
 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, join } from 'node:path';
+import { mkdirSync, existsSync, rmSync, renameSync } from 'node:fs';
+import { dirname, join, basename } from 'node:path';
 import { autoModeForHeader, selectModeFromResourceManager, } from './AdaptiveDiskAnnModeSelector.js';
 /**
  * Node-count threshold above which `useMmapAdjacency: 'auto'`
@@ -1174,13 +1174,50 @@ export class NativeDiskAnnWrapper {
         // into the new base. Their entries are read back through the existing
         // readVectorChunk/slotIdsForSlots surface (each segment is bounded-small
         // by construction, ≤ the delta budget, so this stays bounded RAM).
-        const builtL0 = [...this.l0Segments];
-        const l0Data = builtL0.map((seg) => ({
-            ints: (seg.nodeCount > 0
-                ? seg.native.slotIdsForSlots(Array.from({ length: seg.nodeCount }, (_, i) => i))
-                : []),
-            vecs: seg.native.readVectorChunk(0, seg.nodeCount),
-        }));
+        //
+        // SEGMENT QUARANTINE (3.0.19, accord 2026-07-14): a segment whose
+        // read-back throws (June-class dim poisoning — "Range … out of bounds")
+        // used to abort the WHOLE fold, forever: 545 live segments accumulated,
+        // the write brake engaged, and the board refused writes for 20 hours.
+        // A poisoned segment is now dropped from the fold LOUDLY and its files
+        // moved to <indexDir>/quarantine/ (preserved for forensics, never
+        // deleted); the fold completes with the healthy segments and the same
+        // pass restores the lost entries from canonical (hydrate below), so the
+        // rebuilt base is COMPLETE — serving-truth holds without a second heal.
+        const builtL0 = [];
+        const l0Data = [];
+        const poisonedL0 = [];
+        for (const seg of this.l0Segments) {
+            try {
+                const ints = (seg.nodeCount > 0
+                    ? seg.native.slotIdsForSlots(Array.from({ length: seg.nodeCount }, (_, i) => i))
+                    : []);
+                const vecs = seg.native.readVectorChunk(0, seg.nodeCount);
+                builtL0.push(seg);
+                l0Data.push({ ints, vecs });
+            }
+            catch (error) {
+                poisonedL0.push(seg);
+                prodLog.error(`NativeDiskAnnWrapper: L0 segment ${seg.file} is UNREADABLE ` +
+                    `(${error instanceof Error ? error.message : String(error)}) — ` +
+                    `QUARANTINED (${seg.nodeCount} entries; restored from canonical in this fold)`);
+            }
+        }
+        if (poisonedL0.length > 0) {
+            await this.quarantineSegments(poisonedL0);
+            if (typeof this.storage?.getNouns === 'function') {
+                // Quarantine fold: the poisoned segments' entries exist ONLY in
+                // canonical now — hydrate the delta BEFORE the dedup sets below are
+                // computed, so newest-wins exclusion sees the full canonical set
+                // (base slots excluded for delta ids, healthy-L0 rows deduped
+                // against the delta — no duplicate ints, complete output).
+                // O(canonical) reads, paid only on an actual corruption event —
+                // the alternative (a base silently missing entities) violates
+                // serving-truth. A scoped missing-ids-only backfill rides the M3
+                // fact-log scan path.
+                await this.hydrateDeltaFromStorage(this.config.dimensions);
+            }
+        }
         // Tombstone ints (used to exclude entries from BOTH the base and the L0
         // read-back). Ids never indexed have no int — nothing to exclude.
         const tombIntKeys = new Set();
@@ -1256,11 +1293,14 @@ export class NativeDiskAnnWrapper {
         let dim = this.config.dimensions ??
             (this.native ? this.native.header().dim : undefined) ??
             builtL0.find((s) => s.nodeCount > 0)?.native.header().dim;
-        if (liveOldSlots.length === 0 && typeof this.storage?.getNouns === 'function') {
+        if (liveOldSlots.length === 0 &&
+            poisonedL0.length === 0 &&
+            typeof this.storage?.getNouns === 'function') {
             const probe = await this.storage.getNouns({ pagination: { limit: 1 } });
             if (probe.totalCount === undefined || probe.totalCount > this.delta.size) {
                 // Cold/restore rebuild: hydrate also adopts the dim from canonical data
                 // when we still don't have it, and returns the width it used.
+                // (A quarantine fold already hydrated ABOVE, before the dedup sets.)
                 dim = await this.hydrateDeltaFromStorage(dim);
             }
         }
@@ -1461,6 +1501,37 @@ export class NativeDiskAnnWrapper {
     segPath(file) {
         return `${dirname(this.config.indexPath)}/${file}`;
     }
+    /**
+     * Move poisoned L0 segments out of the live set into
+     * `<indexDir>/quarantine/` — preserved for forensics, NEVER deleted
+     * (accord's 545 poisoned segments were the evidence that convicted the
+     * June dim bug). Crash-safe order: the manifest stops referencing the
+     * segments FIRST (a crash after that leaves orphaned, de-referenced
+     * files — a harmless leak), then the files move. The dropped native
+     * handles close with their references; nothing reads a de-referenced
+     * segment.
+     */
+    async quarantineSegments(poisoned) {
+        const drop = new Set(poisoned.map((s) => s.id));
+        this.l0Segments = this.l0Segments.filter((s) => !drop.has(s.id));
+        await this.saveSegmentManifest();
+        const qDir = join(dirname(this.config.indexPath), 'quarantine');
+        for (const seg of poisoned) {
+            try {
+                mkdirSync(qDir, { recursive: true });
+                const src = this.segPath(seg.file);
+                const family = [src, this.siblingPath(src, 'slotmap'), this.siblingPath(src, 'slotrev')];
+                for (const p of family) {
+                    if (existsSync(p))
+                        renameSync(p, join(qDir, basename(p)));
+                }
+            }
+            catch (error) {
+                prodLog.error(`NativeDiskAnnWrapper: quarantine move failed for ${seg.file} — ` +
+                    `segment stays de-referenced on disk (manifest no longer lists it)`, error);
+            }
+        }
+    }
     /** Membership across the base + every L0 segment (int → any slot). */
     hasIntAnywhere(int) {
         if (this.native && this.native.hasInt(int))

package/dist/native/types.d.ts

@@ -751,6 +751,31 @@ export interface NativeGraphAdjacencyInstance {
      * when LSM-trees are already loaded from persisted SSTables.
      */
     trackVerbId(verbId: string, verbType: string): void;
+    /**
+     * Full-fidelity membership tracking for the boot heal walk (3.0.19):
+     * roster + per-type union + counts + per-(type, subtype) bucket. The
+     * membership-only walk dropped subtype state, silently emptying
+     * `findConnectedSubtype` after every restart.
+     */
+    trackVerbIdFull(verbId: string, verbTypeIndex: number, subtype: string): void;
+    /**
+     * Serialize every RAM-resident membership structure (roster, per-type
+     * unions, per-(type, subtype) buckets, both count families) to one
+     * strictly-framed buffer for stamped persistence (3.0.19).
+     */
+    serializeVerbMembership(): Buffer;
+    /**
+     * Restore membership from a `serializeVerbMembership` buffer. Throws on
+     * ANY malformation (magic/version/id-space/truncation/trailing bytes) —
+     * the caller falls back to the canonical heal walk. Idempotent overwrite.
+     */
+    loadVerbMembership(buf: Buffer): void;
+    /**
+     * Removal-law removal (3.0.19): removes a verb resolving type/subtype
+     * from cor-owned state (endpoint store / membership buckets) — never
+     * reads canonical. Returns false when unknown/already dead (idempotent).
+     */
+    removeVerbByIdOnly(verbId: string, generation: bigint): boolean;
     /** Clear membership bitmap + relationship counts (rebuild prelude). */
     clearVerbTracking(): void;
     /**
@@ -976,6 +1001,15 @@ export interface NativeMetadataIndexInstance {
      * Never throws; empty index → `true`. Backs the wrapper's `probeConsistency`.
      */
     probeConsistency(): boolean;
+    /**
+     * Suspect-surfacing probe (3.0.19): same bounded walk, but returns the
+     * first suspicious `{field, uuid}` as JSON (null = clean) so the wrapper
+     * can adjudicate it with one canonical read instead of guessing from the
+     * sample MIX.
+     */
+    probeConsistencySuspect(): string | null;
+    /** Mark a field learned-multi-valued after canonical adjudication (3.0.19). */
+    markFieldMultiValue(field: string): void;
     /**
      * Scan for the cross-bucket phantom signature (a query-visible int in >1
      * value bucket of a field) and return up to `maxCandidates` (0 = unlimited)

package/dist/utils/NativeMetadataIndex.js

@@ -1371,24 +1371,33 @@ export class MetadataIndexManager {
     async verifiedUnpostableAllowance() {
         try {
             const stamp = (await this.storage.getMetadata(UNPOSTABLE_STAMP_KEY));
-            if (!stamp || typeof stamp.nounCount !== 'number' || stamp.nounCount <= 0)
+            if (!stamp)
                 return 0;
+            // Completion-gap portion (3.0.19): canonical rows a COMPLETED walk
+            // could not even enumerate (no ids exist to re-verify) — count-only
+            // by nature, refreshed on every completed rebuild. The detector's
+            // "FULLY explained by" line reports it whenever it carries the floor.
+            const gap = typeof stamp.completionGap === 'number' && stamp.completionGap > 0
+                ? stamp.completionGap
+                : 0;
+            if (typeof stamp.nounCount !== 'number' || stamp.nounCount <= 0)
+                return gap;
             if (Array.isArray(stamp.nounIds) && stamp.nounIds.length === stamp.nounCount) {
                 const getMeta = this.storage.getNounMetadata;
                 if (typeof getMeta !== 'function')
-                    return stamp.nounCount;
+                    return stamp.nounCount + gap;
                 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;
+                return stillUnpostable + gap;
             }
             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;
+            return stamp.nounCount + gap;
         }
         catch {
             return 0;
@@ -2847,7 +2856,53 @@ export class MetadataIndexManager {
                 await this.ensureFieldLoaded(field);
                 loaded++;
             }
-            return this.native.probeConsistency();
+            // Adjudicated probe (3.0.19): the native walk surfaces ONE suspect
+            // {field, uuid}; a single canonical read decides it. ≥2 current
+            // values = a mixed-length ARRAY field, not a phantom — learned,
+            // persisted, and the probe re-runs (each pass retires one field
+            // permanently, so this converges in ≤ field count; bounded harder
+            // below). Anything else = a genuine phantom → false, exactly the old
+            // detection strength. This replaces the MIX guess whose verdict
+            // depended on which ints the sample happened to draw (accord's brain:
+            // clean boots 1–2, failing boot 3, identical bytes).
+            if (typeof this.native.probeConsistencySuspect !== 'function') {
+                // Pre-3.0.19 binary: no adjudication surface — use the sampled MIX
+                // verdict. WITHOUT this explicit fallback the call below throws into
+                // the outer catch, which assumes healthy — i.e. a stale binary would
+                // silently DISABLE phantom detection (the 3.0.12–3.0.15 class).
+                return this.native.probeConsistency();
+            }
+            const MAX_ADJUDICATIONS = 8;
+            for (let i = 0; i <= MAX_ADJUDICATIONS; i++) {
+                const suspectJson = this.native.probeConsistencySuspect();
+                if (!suspectJson)
+                    return true;
+                if (i === MAX_ADJUDICATIONS)
+                    return false;
+                const { field, uuid } = JSON.parse(suspectJson);
+                let currentValues = [];
+                try {
+                    const noun = await this.storage.getNoun(uuid);
+                    if (noun) {
+                        const raw = resolveEntityField(noun, field);
+                        if (raw !== undefined && raw !== null) {
+                            currentValues = Array.isArray(raw) ? raw : [raw];
+                        }
+                    }
+                }
+                catch {
+                    // Unreadable canonical = cannot exonerate — keep the phantom verdict.
+                }
+                if (currentValues.length < 2)
+                    return false;
+                this.native.markFieldMultiValue(field);
+                const json = this.native.saveFieldIndex(field);
+                if (json) {
+                    await this.storage.saveMetadata(`__metadata_field_index__field_${field}`, JSON.parse(json));
+                }
+                prodLog.info(`[probeConsistency] field '${field}' adjudicated multi-valued against canonical (${currentValues.length} current values) — learned + persisted, exempt from phantom checks`);
+            }
+            return false;
         }
         catch (error) {
             // A probe must never throw into the read path — assume healthy.
@@ -2943,6 +2998,14 @@ export class MetadataIndexManager {
                     purged++;
                     repairedFields.add(field);
                 }
+                // MULTI-VALUE LEARNING persistence (3.0.19): ≥2 current values
+                // proves the field is array-shaped — the native side just learned
+                // it (probe/detector exemption); persist the flag with the field
+                // index or the next cold boot re-flags the same candidates
+                // forever (accord's 166-loop, second mechanism).
+                if (currentValues.length >= 2) {
+                    repairedFields.add(field);
+                }
             }
             catch (error) {
                 prodLog.warn(`[purgeCrossBucketPhantoms] repair of ${uuid}.${field} failed: ${error}`);
@@ -3073,12 +3136,52 @@ export class MetadataIndexManager {
             // detector uses the honest floor instead of re-flagging the same
             // cohort forever. Refreshed on every completed rebuild; an empty
             // set clears the stamp.
+            //
+            // COMPLETION GAP (3.0.19, memory's 52): canonical rows the walk
+            // CANNOT enumerate — dangling counter rows with no readable record —
+            // never appear in items, so the per-id stamp stayed EMPTY while the
+            // detector's canonical count still included them: every detector
+            // boot re-healed (~11 min on memory-vm) forever. A COMPLETED walk is
+            // the strongest possible statement of "everything enumerable is
+            // posted", so the residual canonical-minus-walked difference is
+            // stamped as a count-only allowance (invisible rows have no ids).
+            // Bounded staleness: refreshed on every completed walk; brainy's
+            // counter recount (8.3.2 repairIndex) removes the gap permanently.
+            const walked = nounResult.processed + nounResult.noMetadata;
+            let completionGap = 0;
+            let canonicalAtCompletion;
+            try {
+                const getNouns = this.storage.getNouns;
+                if (typeof getNouns === 'function') {
+                    const probe = await getNouns.call(this.storage, { pagination: { limit: 1 } });
+                    const canonical = probe?.totalCount;
+                    if (typeof canonical === 'number' &&
+                        Number.isFinite(canonical) &&
+                        canonical < 0xffff_ffff) {
+                        canonicalAtCompletion = canonical;
+                        completionGap = Math.max(0, canonical - walked);
+                    }
+                }
+            }
+            catch {
+                // Gap probe is advisory — a failed canonical read stamps no gap
+                // (may over-heal next boot, never under-detects).
+            }
             await this.storage.saveMetadata(UNPOSTABLE_STAMP_KEY, {
                 nounCount: nounResult.noMetadata,
                 nounIds: nounResult.noMetadataIds,
                 verbCount: verbResult.noMetadata,
+                completionGap,
+                canonicalAtCompletion,
                 verifiedAt: Date.now(),
             });
+            if (completionGap > 0) {
+                opsLine(`rebuild: canonical reports ${canonicalAtCompletion} nouns but only ` +
+                    `${walked} were enumerable by a COMPLETED walk — the ${completionGap}-entity ` +
+                    `gap is stamped as a completion-gap allowance (unenumerable canonical ` +
+                    `rows, e.g. inflated counters; a brainy counter recount removes them ` +
+                    `permanently). Boots stop re-healing over this gap.`);
+            }
             opsLine(`Metadata index rebuild completed! Processed ${nounResult.processed} nouns and ` +
                 `${verbResult.processed} verbs` +
                 (nounResult.noMetadata > 0

package/dist/version.d.ts

@@ -11,5 +11,5 @@
  * `check:brainy`-style drift between the two fails the release.
  */
 /** The @soulcraft/cor version this build was cut from. */
-export declare const COR_VERSION = "3.0.18";
+export declare const COR_VERSION = "3.0.19";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -11,5 +11,5 @@
  * `check:brainy`-style drift between the two fails the release.
  */
 /** The @soulcraft/cor version this build was cut from. */
-export const COR_VERSION = '3.0.18';
+export const COR_VERSION = '3.0.19';
 //# sourceMappingURL=version.js.map

package/native/index.d.ts

@@ -722,6 +722,18 @@ export declare class NativeGraphAdjacencyIndex {
    * solely for legacy-data remove paths.
    */
   removeVerb(verbId: string, verbTypeIndex: number, subtype: string, generation: bigint): void
+  /**
+   * **Removal law (3.0.19)**: removal must never require reading the
+   * thing being removed. The JS remove path read the verb's CANONICAL
+   * row to learn (type, subtype) and silently SKIPPED removal when that
+   * row was unreadable — a ghost's graph rows survived forever (the
+   * third instance of the anti-pattern, this one cor's own). This
+   * variant resolves everything from cor-owned state: type from the
+   * endpoint store (or the per-type unions for membership-only verbs),
+   * subtype by scanning that type's buckets for the interned id.
+   * Returns `false` when the id is unknown or already dead (idempotent).
+   */
+  removeVerbByIdOnly(verbId: string, generation: bigint): boolean
   /**
    * **Look up a verb's endpoints by verb-ID.** Returns
    * `{sourceInt, targetInt}` (as u64 BigInts) when the verb was
@@ -999,6 +1011,43 @@ export declare class NativeGraphAdjacencyIndex {
    * counts converge to the same totals).
    */
   trackVerbId(verbId: string, verbType: string): void
+  /**
+   * Membership-only tracking that ALSO restores the per-(type, subtype)
+   * bucket and subtype count — the full-fidelity variant of
+   * [`track_verb_id`](Self::track_verb_id) for the boot heal walk.
+   * The membership-only walk used to drop subtype state entirely, so
+   * `findConnectedSubtype` silently returned nothing after a restart
+   * until a full adjacency rebuild happened to run (3.0.19 find).
+   * Same empty-string escape as the add path: `subtype: ''` tracks
+   * type-level membership only, never an empty-string bucket.
+   */
+  trackVerbIdFull(verbId: string, verbTypeIndex: number, subtype: string): void
+  /**
+   * Serialize EVERY RAM-resident membership structure to one buffer so
+   * the JS wrapper can persist it as a stamped family member (3.0.19:
+   * the roster/buckets/counts were RAM-only, costing every boot an
+   * O(all-canonical-verbs) walk and silently emptying subtype filters).
+   * Format v1, little-endian, strictly length-framed:
+   * magic 'CVMB' u32 | version u8 | idSpace u8 (0=U32, 1=U64) |
+   * roster (u32 len + portable bytes) |
+   * u8 nUnions { u8 typeIdx, u32 len, bytes } |
+   * u32 nSubBuckets { u8 typeIdx, u16 subLen, utf8, u32 len, bytes } |
+   * u8 nCounts { u8 typeIdx, u64 count } |
+   * u32 nSubCounts { u8 typeIdx, u16 subLen, utf8, u64 count }
+   * Subtype keys are emitted sorted so identical state yields identical
+   * bytes (the stamp records the exact byte size).
+   */
+  serializeVerbMembership(): Buffer
+  /**
+   * Restore every membership structure from a
+   * [`serialize_verb_membership`](Self::serialize_verb_membership)
+   * buffer. Strict total parse: ANY malformation (bad magic/version,
+   * id-space mismatch with this index, truncation, trailing bytes,
+   * out-of-range type index) throws so the caller falls back to the
+   * canonical heal walk — a torn blob must never half-load silently.
+   * Clears existing membership state first (idempotent overwrite).
+   */
+  loadVerbMembership(buf: Buffer): void
   /**
    * Clear membership bitmap + relationship counts. Used before
    * rebuild to ensure clean state. The verb-ID namespace's
@@ -1870,6 +1919,23 @@ export declare class NativeMetadataIndex {
    * read path.
    */
   probeConsistency(): boolean
+  /**
+   * The suspect-surfacing probe (3.0.19): same bounded walk as
+   * `probeConsistency`, but instead of a bare verdict it returns the FIRST
+   * suspicious `{field, uuid}` as JSON (None = clean). The TS wrapper
+   * ADJUDICATES the suspect with one canonical read — ≥2 current values
+   * proves the field is array-shaped (learned + persisted, probe re-runs),
+   * anything else is a genuine phantom (probe fails). This replaces the
+   * MIX guess whose verdict depended on WHICH ints the sample drew —
+   * accord's brain passed boots 1–2 and failed boot 3 on identical bytes.
+   */
+  probeConsistencySuspect(): string | null
+  /**
+   * Mark a field as learned-multi-valued (3.0.19). Called by the TS
+   * wrapper after canonical adjudication proves an entity legitimately
+   * holds ≥2 values for the field. The caller persists the field index.
+   */
+  markFieldMultiValue(field: string): void
   /**
    * **Phantom triad — state-level scan (matrix 7.8b).** Find every
    * query-visible int that sits in MORE THAN ONE value bucket of a field —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.18",
+  "version": "3.0.19",
   "description": "Native Rust acceleration for Brainy — SIMD distance, vector quantization, zero-copy mmap, native embeddings. Free tier for storage, Pro license for compute acceleration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -82,7 +82,7 @@
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.0.0",
-    "@soulcraft/brainy": "8.3.0",
+    "@soulcraft/brainy": "8.3.2",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",