@soulcraft/cor 3.0.19 → 3.0.20

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -92,6 +92,8 @@ export declare class GraphAdjacencyIndex implements GraphIndexProvider {
     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?;

package/dist/graph/NativeGraphAdjacencyIndex.js

@@ -14,6 +14,7 @@
  */
 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';
@@ -58,6 +59,26 @@ const GRAPH_VERB_NS_PROBE_KEY = '_graph_verb_ns/x';
  */
 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`)
@@ -110,6 +131,8 @@ export class GraphAdjacencyIndex {
     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;
@@ -369,23 +392,29 @@ export class GraphAdjacencyIndex {
                 this.lastMembershipBlobBytes = blob.length;
                 this.membershipDirty = false;
             }
-            const trees = {};
+            const invariants = {
+                blobBytes: this.lastMembershipBlobBytes,
+            };
             for (const treeName of this.native.treeNames()) {
-                trees[treeName] = this.treeFingerprint(treeName);
+                invariants[`tree:${treeName}`] = this.treeFingerprint(treeName);
             }
-            const body = JSON.stringify({ v: 1, blobBytes: this.lastMembershipBlobBytes, trees });
+            const body = JSON.stringify(invariants);
             if (body === this.lastMembershipStampBody)
                 return;
             const stamp = {
-                v: 1,
-                committedAt: Date.now(),
-                blobBytes: this.lastMembershipBlobBytes,
-                trees,
+                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) {
@@ -405,8 +434,8 @@ export class GraphAdjacencyIndex {
             return false;
         try {
             const meta = await this.storage.getMetadata(GRAPH_MEMBERSHIP_STAMP_KEY);
-            const stamp = meta?.data;
-            if (!stamp || stamp.v !== 1)
+            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) {
@@ -422,11 +451,11 @@ export class GraphAdjacencyIndex {
             }
             this.native.loadVerbMembership(blob);
             this.lastMembershipBlobBytes = blob.length;
-            this.lastMembershipStampBody = JSON.stringify({
-                v: 1,
-                blobBytes: stamp.blobBytes,
-                trees: stamp.trees,
-            });
+            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;

package/dist/hnsw/NativeDiskAnnWrapper.d.ts

@@ -458,6 +458,15 @@ 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

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -78,6 +78,7 @@ import { prodLog } from '@soulcraft/brainy/internals';
 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
@@ -1412,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
@@ -1501,6 +1503,17 @@ 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
@@ -1746,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 });
@@ -1858,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/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. */
@@ -1406,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
@@ -2664,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

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.19";
+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.19';
+export const COR_VERSION = '3.0.20';
 //# sourceMappingURL=version.js.map

package/native/index.d.ts

@@ -2629,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.19",
+  "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.2",
+    "@soulcraft/brainy": "8.5.0",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",