@nxuss/lemma 1.14.0 → 1.15.0

package/dist/cjs/subconscious/TheBrainV2.d.ts

@@ -53,6 +53,16 @@ export interface BrainEntry {
      * still applies, so every entry written before this existed keeps working unchanged.
      */
     symbolHashes?: Record<string, string>;
+    /**
+     * Fase D: sha256 of the same symbols as symbolHashes, but of their normalized
+     * (comment/whitespace-stripped) source — see normalizeForFreshness. Always computed
+     * alongside symbolHashes when a symbol is stored, regardless of whether semanticDiff is
+     * ever used. Lets checkEntryFreshness tell "only a comment/formatting changed" apart from
+     * a real change, but only when the caller opts in via semanticDiff — absent (entries
+     * written before this existed) means that classification isn't possible and a raw-hash
+     * mismatch falls back to stale, same as pre-Fase-D behavior.
+     */
+    symbolNormalizedHashes?: Record<string, string>;
     /**
      * Sub-claims within `response`, each with its own evidence. Absent means the whole
      * entry is one claim, judged by fileHashes/symbolHashes above (pre-existing behavior).
@@ -67,12 +77,23 @@ export interface BrainEntry {
      * "reuse turned out to be wrong." Absent/0 means never downvoted.
      */
     demerits?: number;
+    /**
+     * Ids of other entries/claims this memory's conclusion was built on top of (the agent
+     * read memory A, then stored B as a conclusion derived from it). Absent means B's
+     * freshness is judged only by its own fileHashes/symbolHashes, same as before this
+     * existed. When present, checkEntryFreshness walks it transitively (bounded by
+     * MAX_DERIVED_DEPTH): if A goes stale, B is stale too even though B's own evidence
+     * never changed — because B's conclusion was never independently verified against
+     * current state, only inherited.
+     */
+    derivedFrom?: string[];
 }
 export interface Claim {
     id: string;
     text: string;
     fileHashes?: Record<string, string>;
     symbolHashes?: Record<string, string>;
+    symbolNormalizedHashes?: Record<string, string>;
 }
 export interface ClaimInput {
     text: string;
@@ -84,6 +105,23 @@ export interface ClaimFreshness {
     text: string;
     fresh: boolean;
     staleFiles?: string[];
+    /** Fase D, only set under semanticDiff: symbols whose raw hash changed but only cosmetically. */
+    cosmeticChanges?: string[];
+}
+/**
+ * Result of a single id passed to `TheBrainV2.verifyByIds`. `id` may be an entry id or a
+ * claim id — the caller doesn't need to know which, since both are opaque ids handed back
+ * by a prior search_memory/store_memory call. "unknown" (never "fresh") is what a caller
+ * gets for a purged entry, a renamed symbol's old claim, or an id from another project.
+ */
+export interface VerifyMemoryResult {
+    id: string;
+    status: 'fresh' | 'stale' | 'unknown';
+    staleFiles?: string[];
+    /** Only set when `id` resolved to an entry that itself has per-claim tracking. */
+    claimBreakdown?: ClaimFreshness[];
+    /** Fase D, only set under semanticDiff: symbols whose raw hash changed but only cosmetically. */
+    cosmeticChanges?: string[];
 }
 export interface SymbolRef {
     /** Relative or absolute; resolved against process.cwd() the same way filePaths is. */
@@ -102,6 +140,8 @@ export interface BrainSearchResult {
     outcome?: 'confirmed' | 'failed';
     claims?: ClaimFreshness[];
     domain?: string;
+    /** Fase D, only set under semanticDiff: symbols whose raw hash changed but only cosmetically. */
+    cosmeticChanges?: string[];
 }
 export interface BrainSearchOptions {
     /**
@@ -114,6 +154,14 @@ export interface BrainSearchOptions {
     projectId?: string;
     /** Prefer memories tagged with this domain. Same soft-fallback rule as projectId. */
     domain?: string;
+    /**
+     * Fase D, opt-in and off by default: when a tracked symbol's raw hash changed, check
+     * whether its normalized (comment/whitespace-stripped) hash also changed before marking
+     * stale. Only a real change still marks stale; a comment/formatting-only edit doesn't.
+     * Requires the entry to have been stored with symbolNormalizedHashes — an older entry
+     * without it still falls back to raw-hash-only (stale), same as with the flag off.
+     */
+    semanticDiff?: boolean;
 }
 export interface BrainStats {
     totalEntries: number;
@@ -152,6 +200,47 @@ export declare function bm25Score(queryTerms: string[], docTermFreq: Record<stri
  * Jaccard similarity between two term sets.
  */
 export declare function jaccardSimilarity(setA: Set<string>, setB: Set<string>): number;
+/** A `derivedFrom` id resolves to either a full entry or one of its claims. */
+export type FreshnessNode = {
+    kind: 'entry';
+    entry: BrainEntry;
+} | {
+    kind: 'claim';
+    claim: Claim;
+};
+/**
+ * Looks up a `derivedFrom` id against both entries and claims in one pass. `claimIndex`
+ * is built once per outer call (search/verifyByIds) and threaded through recursion,
+ * never rebuilt per level — rebuilding per level would turn a bounded-depth walk into
+ * O(depth * entries) work for no reason.
+ */
+export declare function resolveFreshnessNode(entries: Map<string, BrainEntry>, claimIndex: Map<string, Claim>, id: string): FreshnessNode | undefined;
+/** Builds an id -> Claim index across every entry's claims, for resolveFreshnessNode. */
+export declare function buildClaimIndex(entries: Map<string, BrainEntry>): Map<string, Claim>;
+/**
+ * Bound on how many `derivedFrom` hops checkEntryFreshness will walk. Procedence chains
+ * are meant to be short (a conclusion built on a conclusion, maybe twice); an unbounded
+ * walk would turn every search() result into a full graph traversal.
+ */
+export declare const MAX_DERIVED_DEPTH = 3;
+/**
+ * True only if every file/symbol this entry was recorded against still hashes the same,
+ * AND (when `derivedFrom` is present and a resolver was passed) every memory this one was
+ * built on top of is itself still fresh, walked up to MAX_DERIVED_DEPTH hops. A file that
+ * also has a tracked symbol is judged by the symbol's hash, not the whole file's — an edit
+ * elsewhere in the same file (a different function, an import, a comment) must not
+ * invalidate a memory that was only ever about one specific symbol.
+ */
+export declare function checkEntryFreshness(entry: BrainEntry, resolveNode?: (id: string) => FreshnessNode | undefined, depth?: number, visited?: Set<string>, semanticDiff?: boolean): {
+    fresh: boolean;
+    staleFiles: string[];
+    cosmeticChanges?: string[];
+};
+/**
+ * Same hash-compare as checkEntryFreshness, scoped to one claim's own evidence — a claim
+ * with no fileHashes/symbolHashes at all is always fresh (nothing tracked to go stale).
+ */
+export declare function checkClaimFreshness(claim: Claim, semanticDiff?: boolean): ClaimFreshness;
 export declare class TheBrainV2 {
     private entries;
     private invertedIndex;
@@ -171,7 +260,7 @@ export declare class TheBrainV2 {
      * Store a query+response pair in the brain.
      * Returns false if detected as duplicate (>= dupThreshold similarity).
      */
-    store(query: string, response: string, provider?: string, dupThreshold?: number, filePaths?: string[], projectId?: string, outcome?: 'confirmed' | 'failed', symbolRefs?: SymbolRef[], claimInputs?: ClaimInput[], domain?: string): {
+    store(query: string, response: string, provider?: string, dupThreshold?: number, filePaths?: string[], projectId?: string, outcome?: 'confirmed' | 'failed', symbolRefs?: SymbolRef[], claimInputs?: ClaimInput[], domain?: string, derivedFrom?: string[]): {
         stored: boolean;
         reason: string;
         duplicate?: BrainSearchResult;
@@ -229,6 +318,16 @@ export declare class TheBrainV2 {
         ok: boolean;
         message: string;
     };
+    /**
+     * Revalidate ids from a prior search_memory/store_memory result via hash-compare only —
+     * no BM25, no `search()`. `ids` may mix entry ids and claim ids freely; each resolves
+     * independently and unknown ids fail closed to "unknown", never "fresh" (an id may be
+     * unknown because the entry was purged, or because the symbol it named was renamed —
+     * either way there is nothing left to vouch for it).
+     */
+    verifyByIds(ids: string[], options?: {
+        semanticDiff?: boolean;
+    }): VerifyMemoryResult[];
     getStats(): BrainStats;
     clear(): void;
 }

package/dist/cjs/subconscious/TheBrainV2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TheBrainV2.d.ts","sourceRoot":"","sources":["../../../src/subconscious/TheBrainV2.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TheBrainV2.d.ts","sourceRoot":"","sources":["../../../src/subconscious/TheBrainV2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAInB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,kFAAkF;IAClF,cAAc,CAAC,EAAE,cAAc,EAAE,CAAC;IAClC,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IACjC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAqBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAqCnE;AAID;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA+D/C;AAoDD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMvE;AAgBD,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAa;gBAEb,UAAU,CAAC,EAAE,MAAM;IAQ/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOvB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQ1B,SAAS,IAAI,MAAM;CAGpB;AAID,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAAE,EACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAO9E;AAwDD,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEnG;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EAC9B,EAAE,EAAE,MAAM,GACT,aAAa,GAAG,SAAS,CAM3B;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAOpF;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,EACvD,KAAK,SAAI,EACT,OAAO,GAAE,GAAG,CAAC,MAAM,CAAa,EAChC,YAAY,UAAQ,GACnB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAiEtE;AAeD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,UAAQ,GAAG,cAAc,CAmDtF;AAID,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAA8C;;IAShE,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,IAAI;IA0CZ,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,IAAI;IAiCZ;;;OAGG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAY,EACpB,YAAY,SAAO,EACnB,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,SAAS,GAAE,MAA0B,EACrC,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,EAChC,UAAU,CAAC,EAAE,SAAS,EAAE,EACxB,WAAW,CAAC,EAAE,UAAU,EAAE,EAC1B,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB;QACD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,iBAAiB,CAAC;QAC9B,SAAS,CAAC,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,CAAA;SAAE,CAAC,CAAC;KACnF;IAoFD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAC3C,6FAA6F;IAC7F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAO;IAE1C;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IA8B3B;;;OAGG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,KAAK,SAAI,EACT,aAAa,SAAI,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,EAAE;IA8JtB;;;OAGG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,EAAE;IAQrD;;;OAGG;IACH,cAAc,CACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,SAAO,GACf;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;KAAE;IA6B7E;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAUtD;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,kBAAkB,EAAE;IAmC1F,QAAQ,IAAI,UAAU;IAWtB,KAAK,IAAI,IAAI;CAad;AAMD,wBAAgB,QAAQ,IAAI,UAAU,CAGrC"}

package/dist/cjs/subconscious/TheBrainV2.js

@@ -14,12 +14,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TheBrainV2 = exports.BloomFilter = void 0;
+exports.TheBrainV2 = exports.MAX_DERIVED_DEPTH = exports.BloomFilter = void 0;
 exports.deriveProjectId = deriveProjectId;
 exports.tokenize = tokenize;
 exports.termFrequencies = termFrequencies;
 exports.bm25Score = bm25Score;
 exports.jaccardSimilarity = jaccardSimilarity;
+exports.resolveFreshnessNode = resolveFreshnessNode;
+exports.buildClaimIndex = buildClaimIndex;
+exports.checkEntryFreshness = checkEntryFreshness;
+exports.checkClaimFreshness = checkClaimFreshness;
 exports.getBrain = getBrain;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -294,33 +298,80 @@ function hashSymbolsForFreshness(refs) {
     for (const ref of refs) {
         const abs = path_1.default.resolve(ref.filePath);
         const key = `${abs}::${ref.symbolName}`;
-        try {
-            const ctx = (0, SymbolSurgicalContext_1.getSymbolSurgicalContext)(path_1.default.dirname(abs), path_1.default.basename(abs), ref.symbolName);
-            hashes[key] = crypto_1.default.createHash('sha256').update(ctx.implementation).digest('hex');
-        }
-        catch {
-            hashes[key] = 'MISSING';
-        }
+        hashes[key] = currentSymbolHashPair(abs, ref.symbolName).raw;
+    }
+    return hashes;
+}
+/**
+ * Fase D companion to hashSymbolsForFreshness: same symbols, hashed after
+ * normalizeForFreshness strips comments/whitespace. Always computed alongside the raw hash
+ * (cheap — same parse) regardless of whether semanticDiff is ever turned on, so an entry
+ * stored with the flag off is still classifiable later if someone turns it on.
+ */
+function hashSymbolsNormalizedForFreshness(refs) {
+    const hashes = {};
+    for (const ref of refs) {
+        const abs = path_1.default.resolve(ref.filePath);
+        const key = `${abs}::${ref.symbolName}`;
+        hashes[key] = currentSymbolHashPair(abs, ref.symbolName).normalized;
     }
     return hashes;
 }
-function currentSymbolHash(abs, symbolName) {
+function currentSymbolHashPair(abs, symbolName) {
     try {
         const ctx = (0, SymbolSurgicalContext_1.getSymbolSurgicalContext)(path_1.default.dirname(abs), path_1.default.basename(abs), symbolName);
-        return crypto_1.default.createHash('sha256').update(ctx.implementation).digest('hex');
+        return {
+            raw: crypto_1.default.createHash('sha256').update(ctx.implementation).digest('hex'),
+            normalized: crypto_1.default.createHash('sha256').update((0, SymbolSurgicalContext_1.normalizeForFreshness)(ctx.implementation)).digest('hex'),
+        };
     }
     catch {
-        return 'MISSING';
+        return { raw: 'MISSING', normalized: 'MISSING' };
+    }
+}
+/**
+ * Looks up a `derivedFrom` id against both entries and claims in one pass. `claimIndex`
+ * is built once per outer call (search/verifyByIds) and threaded through recursion,
+ * never rebuilt per level — rebuilding per level would turn a bounded-depth walk into
+ * O(depth * entries) work for no reason.
+ */
+function resolveFreshnessNode(entries, claimIndex, id) {
+    const entry = entries.get(id);
+    if (entry)
+        return { kind: 'entry', entry };
+    const claim = claimIndex.get(id);
+    if (claim)
+        return { kind: 'claim', claim };
+    return undefined;
+}
+/** Builds an id -> Claim index across every entry's claims, for resolveFreshnessNode. */
+function buildClaimIndex(entries) {
+    const index = new Map();
+    for (const entry of entries.values()) {
+        if (!entry.claims)
+            continue;
+        for (const claim of entry.claims)
+            index.set(claim.id, claim);
     }
+    return index;
 }
 /**
- * True only if every file/symbol this entry was recorded against still hashes the same.
- * A file that also has a tracked symbol is judged by the symbol's hash, not the whole
- * file's — an edit elsewhere in the same file (a different function, an import, a
- * comment) must not invalidate a memory that was only ever about one specific symbol.
+ * Bound on how many `derivedFrom` hops checkEntryFreshness will walk. Procedence chains
+ * are meant to be short (a conclusion built on a conclusion, maybe twice); an unbounded
+ * walk would turn every search() result into a full graph traversal.
  */
-function checkEntryFreshness(entry) {
+exports.MAX_DERIVED_DEPTH = 3;
+/**
+ * True only if every file/symbol this entry was recorded against still hashes the same,
+ * AND (when `derivedFrom` is present and a resolver was passed) every memory this one was
+ * built on top of is itself still fresh, walked up to MAX_DERIVED_DEPTH hops. A file that
+ * also has a tracked symbol is judged by the symbol's hash, not the whole file's — an edit
+ * elsewhere in the same file (a different function, an import, a comment) must not
+ * invalidate a memory that was only ever about one specific symbol.
+ */
+function checkEntryFreshness(entry, resolveNode, depth = 0, visited = new Set(), semanticDiff = false) {
     const staleFiles = [];
+    const cosmeticChanges = [];
     const relLabel = (abs) => {
         const rel = path_1.default.relative(process.cwd(), abs);
         return rel.startsWith('..') ? abs : rel;
@@ -346,12 +397,41 @@ function checkEntryFreshness(entry) {
             const sep = key.lastIndexOf('::');
             const abs = key.substring(0, sep);
             const symbolName = key.substring(sep + 2);
-            if (currentSymbolHash(abs, symbolName) !== storedHash) {
-                staleFiles.push(`${relLabel(abs)}::${symbolName}`);
+            const label = `${relLabel(abs)}::${symbolName}`;
+            const currentPair = currentSymbolHashPair(abs, symbolName);
+            if (currentPair.raw === storedHash)
+                continue;
+            if (semanticDiff) {
+                const storedNormalized = entry.symbolNormalizedHashes?.[key];
+                if (storedNormalized && currentPair.normalized === storedNormalized) {
+                    cosmeticChanges.push(label); // comment/whitespace-only — not stale
+                    continue;
+                }
             }
+            staleFiles.push(label);
+        }
+    }
+    if (entry.derivedFrom && entry.derivedFrom.length > 0 && resolveNode && depth < exports.MAX_DERIVED_DEPTH) {
+        for (const depId of entry.derivedFrom) {
+            if (visited.has(depId))
+                continue; // cycle guard — already accounted for in this chain
+            const node = resolveNode(depId);
+            if (!node) {
+                // Can't verify a dependency that no longer resolves — fail closed, same invariant
+                // as verify_memory's unknown ids.
+                staleFiles.push(`derived:${depId} (unknown)`);
+                continue;
+            }
+            const nextVisited = new Set(visited);
+            nextVisited.add(depId);
+            const depFresh = node.kind === 'entry'
+                ? checkEntryFreshness(node.entry, resolveNode, depth + 1, nextVisited, semanticDiff).fresh
+                : checkClaimFreshness(node.claim, semanticDiff).fresh;
+            if (!depFresh)
+                staleFiles.push(`derived:${depId}`);
         }
     }
-    return { fresh: staleFiles.length === 0, staleFiles };
+    return { fresh: staleFiles.length === 0, staleFiles, ...(cosmeticChanges.length > 0 ? { cosmeticChanges } : {}) };
 }
 /** Builds the persisted `Claim[]` for an entry from the caller-supplied claim inputs. */
 function buildClaims(inputs) {
@@ -362,14 +442,16 @@ function buildClaims(inputs) {
         text: c.text.trim(),
         fileHashes: c.filePaths && c.filePaths.length > 0 ? hashFilesForFreshness(c.filePaths) : undefined,
         symbolHashes: c.symbols && c.symbols.length > 0 ? hashSymbolsForFreshness(c.symbols) : undefined,
+        symbolNormalizedHashes: c.symbols && c.symbols.length > 0 ? hashSymbolsNormalizedForFreshness(c.symbols) : undefined,
     }));
 }
 /**
  * Same hash-compare as checkEntryFreshness, scoped to one claim's own evidence — a claim
  * with no fileHashes/symbolHashes at all is always fresh (nothing tracked to go stale).
  */
-function checkClaimFreshness(claim) {
+function checkClaimFreshness(claim, semanticDiff = false) {
     const staleFiles = [];
+    const cosmeticChanges = [];
     const relLabel = (abs) => {
         const rel = path_1.default.relative(process.cwd(), abs);
         return rel.startsWith('..') ? abs : rel;
@@ -395,12 +477,27 @@ function checkClaimFreshness(claim) {
             const sep = key.lastIndexOf('::');
             const abs = key.substring(0, sep);
             const symbolName = key.substring(sep + 2);
-            if (currentSymbolHash(abs, symbolName) !== storedHash) {
-                staleFiles.push(`${relLabel(abs)}::${symbolName}`);
+            const label = `${relLabel(abs)}::${symbolName}`;
+            const currentPair = currentSymbolHashPair(abs, symbolName);
+            if (currentPair.raw === storedHash)
+                continue;
+            if (semanticDiff) {
+                const storedNormalized = claim.symbolNormalizedHashes?.[key];
+                if (storedNormalized && currentPair.normalized === storedNormalized) {
+                    cosmeticChanges.push(label);
+                    continue;
+                }
             }
+            staleFiles.push(label);
         }
     }
-    return { id: claim.id, text: claim.text, fresh: staleFiles.length === 0, ...(staleFiles.length > 0 ? { staleFiles } : {}) };
+    return {
+        id: claim.id,
+        text: claim.text,
+        fresh: staleFiles.length === 0,
+        ...(staleFiles.length > 0 ? { staleFiles } : {}),
+        ...(cosmeticChanges.length > 0 ? { cosmeticChanges } : {}),
+    };
 }
 // ─── TheBrainV2 ──────────────────────────────────────────────────────────────
 class TheBrainV2 {
@@ -513,7 +610,7 @@ class TheBrainV2 {
      * Store a query+response pair in the brain.
      * Returns false if detected as duplicate (>= dupThreshold similarity).
      */
-    store(query, response, provider = 'generic', dupThreshold = 0.92, filePaths, projectId = deriveProjectId(), outcome, symbolRefs, claimInputs, domain) {
+    store(query, response, provider = 'generic', dupThreshold = 0.92, filePaths, projectId = deriveProjectId(), outcome, symbolRefs, claimInputs, domain, derivedFrom) {
         // Quick bloom check
         const queryKey = query.trim().toLowerCase().substring(0, 200);
         if (this.bloom.has(queryKey)) {
@@ -570,8 +667,10 @@ class TheBrainV2 {
             fileHashes: filePaths && filePaths.length > 0 ? hashFilesForFreshness(filePaths) : undefined,
             outcome,
             symbolHashes: symbolRefs && symbolRefs.length > 0 ? hashSymbolsForFreshness(symbolRefs) : undefined,
+            symbolNormalizedHashes: symbolRefs && symbolRefs.length > 0 ? hashSymbolsNormalizedForFreshness(symbolRefs) : undefined,
             claims: claimInputs && claimInputs.length > 0 ? buildClaims(claimInputs) : undefined,
             domain,
+            derivedFrom: derivedFrom && derivedFrom.length > 0 ? derivedFrom : undefined,
         };
         this.entries.set(id, entry);
         // Update inverted index
@@ -727,12 +826,15 @@ class TheBrainV2 {
         });
         // 6. Sort and filter
         combined.sort((a, b) => b.similarity - a.similarity);
+        const claimIndex = buildClaimIndex(this.entries);
+        const resolveNode = (id) => resolveFreshnessNode(this.entries, claimIndex, id);
+        const semanticDiff = options.semanticDiff === true;
         const results = combined
             .filter(r => r.similarity >= minSimilarity)
             .slice(0, limit)
             .map(r => {
-            const { fresh, staleFiles } = checkEntryFreshness(r.entry);
-            const claims = r.entry.claims?.map(checkClaimFreshness);
+            const { fresh, staleFiles, cosmeticChanges } = checkEntryFreshness(r.entry, resolveNode, 0, new Set(), semanticDiff);
+            const claims = r.entry.claims?.map((c) => checkClaimFreshness(c, semanticDiff));
             return {
                 id: r.entry.id,
                 query: r.entry.query,
@@ -745,6 +847,7 @@ class TheBrainV2 {
                 ...(r.entry.outcome ? { outcome: r.entry.outcome } : {}),
                 ...(claims && claims.length > 0 ? { claims } : {}),
                 ...(r.entry.domain ? { domain: r.entry.domain } : {}),
+                ...(cosmeticChanges && cosmeticChanges.length > 0 ? { cosmeticChanges } : {}),
             };
         });
         // 7. Update hit counters — only for searches a caller actually asked a question with.
@@ -815,6 +918,43 @@ class TheBrainV2 {
         this.scheduleSave();
         return { ok: true, message: `Recorded negative feedback on entry "${id}" (demerits: ${entry.demerits}). It will rank lower and be evicted sooner.` };
     }
+    // ─── Batch verification ─────────────────────────────────────────────────────
+    /**
+     * Revalidate ids from a prior search_memory/store_memory result via hash-compare only —
+     * no BM25, no `search()`. `ids` may mix entry ids and claim ids freely; each resolves
+     * independently and unknown ids fail closed to "unknown", never "fresh" (an id may be
+     * unknown because the entry was purged, or because the symbol it named was renamed —
+     * either way there is nothing left to vouch for it).
+     */
+    verifyByIds(ids, options = {}) {
+        const claimIndex = buildClaimIndex(this.entries);
+        const resolveNode = (id) => resolveFreshnessNode(this.entries, claimIndex, id);
+        const semanticDiff = options.semanticDiff === true;
+        return ids.map((id) => {
+            const entry = this.entries.get(id);
+            if (entry) {
+                const { fresh, staleFiles, cosmeticChanges } = checkEntryFreshness(entry, resolveNode, 0, new Set(), semanticDiff);
+                return {
+                    id,
+                    status: fresh ? 'fresh' : 'stale',
+                    ...(staleFiles.length > 0 ? { staleFiles } : {}),
+                    ...(entry.claims ? { claimBreakdown: entry.claims.map((c) => checkClaimFreshness(c, semanticDiff)) } : {}),
+                    ...(cosmeticChanges && cosmeticChanges.length > 0 ? { cosmeticChanges } : {}),
+                };
+            }
+            const claim = claimIndex.get(id);
+            if (claim) {
+                const cf = checkClaimFreshness(claim, semanticDiff);
+                return {
+                    id,
+                    status: cf.fresh ? 'fresh' : 'stale',
+                    ...(cf.staleFiles ? { staleFiles: cf.staleFiles } : {}),
+                    ...(cf.cosmeticChanges ? { cosmeticChanges: cf.cosmeticChanges } : {}),
+                };
+            }
+            return { id, status: 'unknown' };
+        });
+    }
     // ─── Stats ────────────────────────────────────────────────────────────────
     getStats() {
         return {