@soulcraft/cor 3.0.18 → 3.0.20

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -86,6 +86,16 @@ 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;
+    /** Monotonic stamp lineage (unified shape); restored at load, bumped at persist. */
+    private membershipStampGeneration;
+    /** How this boot obtained membership: restored (stamp), healed (walk), or fresh (no verbs). */
+    private membershipBootState;
     private flushTimer?;
     private rebuildStartTime;
     private totalRelationshipsIndexed;
@@ -174,6 +184,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,8 @@
  * since it coordinates cross-subsystem caching and requires async storage access.
  */
 import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { readCommittedGeneration } from '../utils/generationWatermark.js';
 import { TypeUtils, VerbType } from '@soulcraft/brainy/types/graphTypes';
 import { loadNativeModule } from '../native/index.js';
 import { composeInvariantReport } from '../utils/invariantReport.js';
@@ -45,6 +47,38 @@ 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';
+/** Normalized view both wire shapes reduce to; null = unrecognized. */
+function normalizeMembershipStamp(raw) {
+    const s = raw;
+    if (s?.members?.mode === 'rollup' && s.members.invariants) {
+        const inv = s.members.invariants;
+        const blobBytes = inv.blobBytes;
+        if (typeof blobBytes !== 'number')
+            return null;
+        const trees = {};
+        for (const [k, v] of Object.entries(inv)) {
+            if (k.startsWith('tree:') && typeof v === 'string')
+                trees[k.slice(5)] = v;
+        }
+        return { blobBytes, trees, generation: typeof s.generation === 'number' ? s.generation : 0 };
+    }
+    if (s?.v === 1 && typeof s.blobBytes === 'number' && s.trees) {
+        return { blobBytes: s.blobBytes, trees: s.trees, generation: 0 };
+    }
+    return null;
+}
 /**
  * Resolve a verb-type string to its canonical `VerbTypeEnum` index,
  * falling back to {@link VERB_FALLBACK_INDEX} (`VerbType.RelatedTo`)
@@ -91,6 +125,16 @@ 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;
+    /** Monotonic stamp lineage (unified shape); restored at load, bumped at persist. */
+    membershipStampGeneration = 0;
+    /** How this boot obtained membership: restored (stamp), healed (walk), or fresh (no verbs). */
+    membershipBootState = 'fresh';
     flushTimer;
     rebuildStartTime = 0;
     totalRelationshipsIndexed = 0;
@@ -293,13 +337,132 @@ 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 invariants = {
+                blobBytes: this.lastMembershipBlobBytes,
+            };
+            for (const treeName of this.native.treeNames()) {
+                invariants[`tree:${treeName}`] = this.treeFingerprint(treeName);
+            }
+            const body = JSON.stringify(invariants);
+            if (body === this.lastMembershipStampBody)
+                return;
+            const stamp = {
+                family: 'graph-membership',
+                generation: this.membershipStampGeneration + 1,
+                committedAt: new Date().toISOString(),
+                members: { mode: 'rollup', invariants },
+            };
+            const sourceGeneration = await readCommittedGeneration(this.storage);
+            if (sourceGeneration !== undefined)
+                stamp.sourceGeneration = sourceGeneration;
+            await this.storage.saveMetadata(GRAPH_MEMBERSHIP_STAMP_KEY, {
+                noun: 'thing',
+                data: stamp,
+            });
+            this.membershipStampGeneration = stamp.generation;
+            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 = normalizeMembershipStamp(meta?.data);
+            if (!stamp)
+                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.membershipStampGeneration = stamp.generation;
+            const invariants = { blobBytes: stamp.blobBytes };
+            for (const [name, fp] of Object.entries(stamp.trees))
+                invariants[`tree:${name}`] = fp;
+            this.lastMembershipStampBody = JSON.stringify(invariants);
+            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 +476,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 +604,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 +633,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 +654,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 +780,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 +912,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 +933,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 +956,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 +1006,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 +1240,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,26 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
     getPersistMode(): 'immediate' | 'deferred';
     /** Absolute path of a segment file (lives next to the base indexPath). */
     private segPath;
+    /**
+     * The committed-transaction watermark (M3 PD-2 `sourceGeneration`): read
+     * from brainy's generation manifest (`_system/manifest.json`, the same
+     * object the generation store treats as committed truth). Read-only and
+     * ADVISORY — hosts without the manifest (or a faulted read) stamp no
+     * sourceGeneration and verifiers skip the comparison. Never constructs a
+     * FactLog (its open() is writer-side reconciliation).
+     */
+    private readCommittedGeneration;
+    /**
+     * 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,9 +75,10 @@ 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';
+import { readCommittedGeneration } from '../utils/generationWatermark.js';
 /**
  * Node-count threshold above which `useMmapAdjacency: 'auto'`
  * resolves to file-backed. Below this, the in-RAM build adjacency
@@ -1174,13 +1175,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 +1294,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);
             }
         }
@@ -1372,6 +1413,7 @@ export class NativeDiskAnnWrapper {
             outputPath: this.config.indexPath,
             cfg,
             slotIds: slotIdsBuf,
+            sourceGeneration: await this.readCommittedGeneration(),
         });
         // Atomic swap. The native engine now owns both off-heap slotmaps
         // (written inside rebuildFromExisting), so there is NO resident
@@ -1461,6 +1503,48 @@ export class NativeDiskAnnWrapper {
     segPath(file) {
         return `${dirname(this.config.indexPath)}/${file}`;
     }
+    /**
+     * The committed-transaction watermark (M3 PD-2 `sourceGeneration`): read
+     * from brainy's generation manifest (`_system/manifest.json`, the same
+     * object the generation store treats as committed truth). Read-only and
+     * ADVISORY — hosts without the manifest (or a faulted read) stamp no
+     * sourceGeneration and verifiers skip the comparison. Never constructs a
+     * FactLog (its open() is writer-side reconciliation).
+     */
+    async readCommittedGeneration() {
+        return readCommittedGeneration(this.storage);
+    }
+    /**
+     * 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))
@@ -1675,6 +1759,7 @@ export class NativeDiskAnnWrapper {
             outputPath: this.segPath(file),
             cfg,
             slotIds: Buffer.from(slotIdsArr.buffer, slotIdsArr.byteOffset, slotIdsArr.byteLength),
+            sourceGeneration: await this.readCommittedGeneration(),
         });
         // File (+ sidecars) durably on disk → register → manifest (crash-safe order).
         this.l0Segments.push({ id, file, nodeCount: builtDelta.size, native: newNative });
@@ -1787,10 +1872,17 @@ export class NativeDiskAnnWrapper {
                 violations: [`stamp ${stampPath} has no members map — cannot prove family coherence`],
             };
         }
+        // Member sizes, both wire modes (M3 unified stamp, 2026-07-15): the
+        // unified shape carries {mode:'enumerated', files:[{path,bytes}]}; the
+        // legacy cor shape is a flat basename→bytes map. One verifier, one page.
+        const rawMembers = stamp.members;
+        const memberSizes = Array.isArray(rawMembers.files)
+            ? Object.fromEntries(rawMembers.files.map((f) => [f.path, f.bytes]))
+            : stamp.members;
         const dir = dirname(indexPath);
         const violations = [];
         const faults = [];
-        for (const [name, expected] of Object.entries(stamp.members)) {
+        for (const [name, expected] of Object.entries(memberSizes)) {
             try {
                 const actual = statSync(join(dir, name)).size;
                 if (actual !== expected) {

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.d.ts

@@ -858,6 +858,24 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      */
     private flushChain;
     flush(): Promise<void>;
+    /**
+     * Write the metadata index's family stamp (shared shape/functions from
+     * brainy internals): rollup invariant = the posted-entity total the
+     * detector already computes; `sourceGeneration` = the committed
+     * watermark these postings cover. Advisory end to end — a host without
+     * the stamp surface or the watermark simply doesn't stamp, and opens
+     * keep their walk-based healing.
+     */
+    private persistMetadataStamp;
+    /**
+     * M3 PD-4: incremental catch-up from the generation fact log. Applies
+     * exactly the ops in `[fromGeneration, head]` — after-image upserts via
+     * the normal add path (idempotent: eviction removes stale buckets),
+     * tombstones via the id-only removal path (removal law). Returns false
+     * (and logs) on ANY break — no capability, scan gap, apply fault — so
+     * the caller falls back to the walk; a half-replay never claims success.
+     */
+    private replayFactGap;
     private flushOnce;
     /**
      * Persist all state and release the column store's resources. Brainy's

package/dist/utils/NativeMetadataIndex.js

@@ -18,6 +18,7 @@
 import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { prodLog, getGlobalCache, FieldTypeInference, resolveEntityField } from '@soulcraft/brainy/internals';
+import { readCommittedGeneration } from './generationWatermark.js';
 import { compareCodePoints } from './collation.js';
 /**
  * Fields whose values are stored in the sparse index as BUCKETED values
@@ -84,6 +85,33 @@ const LSM_MANIFEST_KEY = '__metadata_lsm_manifest__';
  * CORTEX-RESTART-STRAND 2026-07-13 — four consecutive boots).
  */
 const UNPOSTABLE_STAMP_KEY = '__metadata_verified_unpostable__';
+/**
+ * M3 PD-2/PD-4 (Stage 1): the metadata index's family stamp — written via
+ * brainy's SHARED stamp functions (one verifier, literally one function).
+ * `sourceGeneration` records the committed watermark the postings cover;
+ * a coherent-but-BEHIND stamp at open triggers an incremental FACT REPLAY
+ * of exactly the gap instead of any walk. Path/family per brainy's
+ * FAMILY_STAMPS_PREFIX convention.
+ */
+const METADATA_FAMILY = 'cor-metadata-lsm';
+const METADATA_STAMP_PATH = '_system/family-stamps/cor-metadata-lsm.json';
+let familyStampFnsCache;
+async function familyStampFns() {
+    if (familyStampFnsCache !== undefined)
+        return familyStampFnsCache;
+    try {
+        const internals = (await import('@soulcraft/brainy/internals'));
+        familyStampFnsCache =
+            typeof internals.readFamilyStamp === 'function' &&
+                typeof internals.writeFamilyStamp === 'function'
+                ? internals
+                : null;
+    }
+    catch {
+        familyStampFnsCache = null;
+    }
+    return familyStampFnsCache;
+}
 /** Above this many ids the stamp stores count-only (the boot-time
  * re-verify would stop being cheap); detection then carries a bounded
  * staleness caveat, logged when it engages. */
@@ -1371,24 +1399,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;
@@ -1397,6 +1434,29 @@ export class MetadataIndexManager {
     async detectDerivedStrand() {
         if (!this.lsmEngine || !this.lsmMetaDir)
             return;
+        // M3 PD-4 (Stage 1): a coherent-but-BEHIND family stamp means the
+        // postings simply predate the newest commits — replay EXACTLY the gap
+        // from the generation fact log before any strand verdict, so the
+        // checks below see a caught-up index and no walk fires for what was
+        // never damage. Advisory end to end: any break (no 8.5.0 surface, no
+        // watermark, scan fault) falls through and the detector stays
+        // authoritative.
+        try {
+            const fns = await familyStampFns();
+            const head = await readCommittedGeneration(this.storage);
+            if (fns && head !== undefined) {
+                const stamp = (await fns.readFamilyStamp(this.storage, METADATA_STAMP_PATH));
+                const src = stamp?.family === METADATA_FAMILY ? stamp.sourceGeneration : undefined;
+                if (typeof src === 'number' && src < head) {
+                    if (await this.replayFactGap(src + 1)) {
+                        await this.persistMetadataStamp();
+                    }
+                }
+            }
+        }
+        catch {
+            // Detector below stays authoritative.
+        }
         // 0. Replay-stats verdict (3.0.12). The native open now RECREATES a
         // missing live log and recovers what its archives hold, so the
         // filename census below can no longer see the deleted-live-log
@@ -2655,12 +2715,95 @@ export class MetadataIndexManager {
                 'flush would multiply heal IO).');
             return;
         }
-        const run = this.flushChain.then(() => this.flushOnce());
+        const run = this.flushChain.then(async () => {
+            await this.flushOnce();
+            // M3 Stage 1: the flushed postings durably cover the committed
+            // watermark — stamp it so the next open replays only the gap
+            // (advisory: no-ops without the 8.5.0 stamp surface).
+            await this.persistMetadataStamp();
+        });
         // 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;
     }
+    /**
+     * Write the metadata index's family stamp (shared shape/functions from
+     * brainy internals): rollup invariant = the posted-entity total the
+     * detector already computes; `sourceGeneration` = the committed
+     * watermark these postings cover. Advisory end to end — a host without
+     * the stamp surface or the watermark simply doesn't stamp, and opens
+     * keep their walk-based healing.
+     */
+    async persistMetadataStamp() {
+        try {
+            const fns = await familyStampFns();
+            if (!fns)
+                return;
+            const sourceGeneration = await readCommittedGeneration(this.storage);
+            if (sourceGeneration === undefined)
+                return;
+            const { NounType } = await import('@soulcraft/brainy');
+            let posted = 0;
+            for (const t of Object.values(NounType)) {
+                posted += this.native.getEntityCountByType(t);
+            }
+            await fns.writeFamilyStamp(this.storage, METADATA_STAMP_PATH, {
+                family: METADATA_FAMILY,
+                sourceGeneration,
+                members: { mode: 'rollup', invariants: { posted } },
+            });
+        }
+        catch {
+            // Advisory: a failed stamp means the next open heals the old way.
+        }
+    }
+    /**
+     * M3 PD-4: incremental catch-up from the generation fact log. Applies
+     * exactly the ops in `[fromGeneration, head]` — after-image upserts via
+     * the normal add path (idempotent: eviction removes stale buckets),
+     * tombstones via the id-only removal path (removal law). Returns false
+     * (and logs) on ANY break — no capability, scan gap, apply fault — so
+     * the caller falls back to the walk; a half-replay never claims success.
+     */
+    async replayFactGap(fromGeneration) {
+        const scanFn = this.storage.scanFacts;
+        if (typeof scanFn !== 'function')
+            return false;
+        const scan = scanFn.call(this.storage, { fromGeneration, batchSize: 256 });
+        if (!scan)
+            return false;
+        let upserts = 0;
+        let removals = 0;
+        try {
+            for await (const batch of scan.batches()) {
+                for (const fact of batch.facts) {
+                    for (const op of fact.ops) {
+                        if (op.record === null) {
+                            await this.removeFromIndex(op.id);
+                            removals++;
+                        }
+                        else if (op.record.metadata != null) {
+                            await this.addToIndex(op.id, op.record.metadata, true, true);
+                            upserts++;
+                        }
+                        // record present with null metadata = vector-only write —
+                        // nothing to post here.
+                    }
+                }
+            }
+        }
+        catch (error) {
+            opsLine(`fact replay from generation ${fromGeneration} ABORTED (${String(error)}) — ` +
+                `falling back to the walk-based heal path`);
+            return false;
+        }
+        if (upserts + removals > 0) {
+            opsLine(`fact replay: caught up ${upserts} upsert(s) + ${removals} removal(s) ` +
+                `from the generation log — no walk needed`);
+        }
+        return true;
+    }
     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
@@ -2847,7 +2990,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 +3132,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 +3270,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/utils/generationWatermark.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module utils/generationWatermark
+ * @description The committed-generation watermark (M3 PD-2
+ * `sourceGeneration`) — what a projection stamp records as the source
+ * truth it reflects. Read CAPABILITY-FIRST: brainy 8.5.0 exposes
+ * `storage.committedGeneration()` precisely so providers never parse the
+ * store's private manifest format; the direct `_system/manifest.json`
+ * read remains as the 8.4.0-host fallback for one release line. Advisory
+ * everywhere: `undefined` (no capability, no manifest, faulted read)
+ * means the stamp carries no sourceGeneration and verifiers skip the
+ * comparison — never a blocked write, never a guessed value.
+ */
+/** Best-effort committed watermark; `undefined` when unknowable. */
+export declare function readCommittedGeneration(storage: unknown): Promise<number | undefined>;
+//# sourceMappingURL=generationWatermark.d.ts.map

package/dist/utils/generationWatermark.js

@@ -0,0 +1,35 @@
+/**
+ * @module utils/generationWatermark
+ * @description The committed-generation watermark (M3 PD-2
+ * `sourceGeneration`) — what a projection stamp records as the source
+ * truth it reflects. Read CAPABILITY-FIRST: brainy 8.5.0 exposes
+ * `storage.committedGeneration()` precisely so providers never parse the
+ * store's private manifest format; the direct `_system/manifest.json`
+ * read remains as the 8.4.0-host fallback for one release line. Advisory
+ * everywhere: `undefined` (no capability, no manifest, faulted read)
+ * means the stamp carries no sourceGeneration and verifiers skip the
+ * comparison — never a blocked write, never a guessed value.
+ */
+/** Best-effort committed watermark; `undefined` when unknowable. */
+export async function readCommittedGeneration(storage) {
+    try {
+        const s = storage;
+        if (typeof s?.committedGeneration === 'function') {
+            const g = s.committedGeneration();
+            if (typeof g === 'number' && Number.isFinite(g) && g >= 0)
+                return g;
+            // Capability present but unwired (bare adapter) — fall through to the
+            // manifest read: a stamped brain opened outside a host brain should
+            // still stamp truthfully when the manifest exists.
+        }
+        if (typeof s?.readRawObject !== 'function')
+            return undefined;
+        const manifest = (await s.readRawObject('_system/manifest.json'));
+        const g = manifest?.generation;
+        return typeof g === 'number' && Number.isFinite(g) && g >= 0 ? g : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=generationWatermark.js.map

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.20";
 //# 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.20';
 //# 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 —
@@ -2563,6 +2629,13 @@ export interface DiskAnnRebuildFromExistingParams {
    * the slot-only benchmark paths that don't carry entity ids.
    */
   slotIds?: Buffer
+  /**
+   * M3 PD-2: the source-of-truth log generation this publish reflects
+   * (the committed watermark the JS wrapper read at rebuild time).
+   * Omitted on hosts without a generation manifest — the stamp then
+   * carries no `sourceGeneration` and verifiers skip the comparison.
+   */
+  sourceGeneration?: number
 }
 
 /** Vamana graph build knobs exposed to JS. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.18",
+  "version": "3.0.20",
   "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.5.0",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",