@nxuss/lemma 1.14.0 → 1.16.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,69 @@ 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;
+export interface BlastRadiusHit {
+    id: string;
+    kind: 'entry' | 'claim';
+    /** entry.query, or the claim's own text when kind === 'claim'. */
+    query: string;
+    outcome?: 'confirmed' | 'failed';
+    /** 'direct' = tracks the edited symbol/file itself; 'derived' = depends (via derivedFrom) on something that does. */
+    via: 'direct' | 'derived';
+}
+export interface BlastRadiusResult {
+    hits: BlastRadiusHit[];
+    /** Subset of hits with outcome === 'failed' — the escalated case worth a stronger warning. */
+    failedHits: BlastRadiusHit[];
+}
+/**
+ * Everything in the Brain that would go stale (directly or transitively via derivedFrom) if
+ * the given symbol/file changes right now — computed BEFORE the write happens, so a write
+ * tool can warn instead of only ever reporting staleness the next time someone searches.
+ * Purely advisory: never blocks, never mutates anything, matches the fail-open/additive
+ * invariant every prior phase of proof-carrying context has kept.
+ */
+export declare function findBlastRadius(entries: Map<string, BrainEntry>, filePath: string, symbolName?: string): BlastRadiusResult;
+/**
+ * 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 +282,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 +340,22 @@ 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[];
+    /**
+     * What in the Brain would go stale, directly or transitively, if `filePath`/`symbolName`
+     * changes right now. Called by write tools BEFORE they'd otherwise find out (only on the
+     * next search) — see findBlastRadius for the algorithm and cost.
+     */
+    findBlastRadius(filePath: string, symbolName?: string): BlastRadiusResult;
     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;AAInC,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IACjC,qHAAqH;IACrH,GAAG,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,8FAA8F;IAC9F,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AA6ED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,iBAAiB,CAqCnB;AAED;;;;;;;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;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,iBAAiB;IAMzE,QAAQ,IAAI,UAAU;IAWtB,KAAK,IAAI,IAAI;CAad;AAMD,wBAAgB,QAAQ,IAAI,UAAU,CAGrC"}

package/dist/cjs/subconscious/TheBrainV2.js

@@ -14,12 +14,17 @@ 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.findBlastRadius = findBlastRadius;
+exports.checkEntryFreshness = checkEntryFreshness;
+exports.checkClaimFreshness = checkClaimFreshness;
 exports.getBrain = getBrain;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -294,33 +299,203 @@ 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;
 }
-function currentSymbolHash(abs, symbolName) {
+/**
+ * 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 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;
+}
+/**
+ * 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.
+ */
+exports.MAX_DERIVED_DEPTH = 3;
+/**
+ * Maps "abs::symbolName" -> the entries/claims whose symbolHashes track that exact symbol.
+ * Rebuilt fresh per call (same pattern as buildClaimIndex) — cheap at the 8,000-entry cap
+ * (measured ~0.04ms per lookup at full capacity), not worth persisting or maintaining
+ * incrementally.
+ */
+function buildSymbolIndex(entries) {
+    const index = new Map();
+    const add = (key, hit) => {
+        const list = index.get(key);
+        if (list)
+            list.push(hit);
+        else
+            index.set(key, [hit]);
+    };
+    for (const entry of entries.values()) {
+        if (entry.symbolHashes) {
+            for (const key of Object.keys(entry.symbolHashes)) {
+                add(key, { id: entry.id, kind: 'entry', query: entry.query, outcome: entry.outcome, via: 'direct' });
+            }
+        }
+        if (entry.claims) {
+            for (const claim of entry.claims) {
+                if (!claim.symbolHashes)
+                    continue;
+                for (const key of Object.keys(claim.symbolHashes)) {
+                    add(key, { id: claim.id, kind: 'claim', query: claim.text, outcome: entry.outcome, via: 'direct' });
+                }
+            }
+        }
+    }
+    return index;
+}
+/**
+ * Maps an absolute file path -> ids of entries whole-file-tracked against it (fileHashes),
+ * for write tools that don't parse AST and so never know which symbol they touched.
+ */
+function buildFileIndex(entries) {
+    const index = new Map();
+    const add = (key, hit) => {
+        const list = index.get(key);
+        if (list)
+            list.push(hit);
+        else
+            index.set(key, [hit]);
+    };
+    for (const entry of entries.values()) {
+        if (entry.fileHashes) {
+            for (const abs of Object.keys(entry.fileHashes)) {
+                add(abs, { id: entry.id, kind: 'entry', query: entry.query, outcome: entry.outcome, via: 'direct' });
+            }
+        }
+        // A file-level fallback should also catch entries that only track a *symbol* in that
+        // file — an untargeted write to the file can plausibly touch it too, and over-reporting
+        // here is the safe direction (this only ever produces an advisory note, never blocks).
+        if (entry.symbolHashes) {
+            const absPaths = new Set(Object.keys(entry.symbolHashes).map((k) => k.substring(0, k.lastIndexOf('::'))));
+            for (const abs of absPaths) {
+                add(abs, { id: entry.id, kind: 'entry', query: entry.query, outcome: entry.outcome, via: 'direct' });
+            }
+        }
     }
+    return index;
+}
+/** Maps a dependency id -> ids of entries whose derivedFrom includes it (Fase B, reversed). */
+function buildDerivedFromReverseIndex(entries) {
+    const index = new Map();
+    for (const entry of entries.values()) {
+        if (!entry.derivedFrom)
+            continue;
+        for (const depId of entry.derivedFrom) {
+            const list = index.get(depId);
+            if (list)
+                list.push(entry.id);
+            else
+                index.set(depId, [entry.id]);
+        }
+    }
+    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.
+ * Everything in the Brain that would go stale (directly or transitively via derivedFrom) if
+ * the given symbol/file changes right now — computed BEFORE the write happens, so a write
+ * tool can warn instead of only ever reporting staleness the next time someone searches.
+ * Purely advisory: never blocks, never mutates anything, matches the fail-open/additive
+ * invariant every prior phase of proof-carrying context has kept.
  */
-function checkEntryFreshness(entry) {
+function findBlastRadius(entries, filePath, symbolName) {
+    const abs = path_1.default.resolve(filePath);
+    const symbolIndex = buildSymbolIndex(entries);
+    const fileIndex = buildFileIndex(entries);
+    const reverseDerived = buildDerivedFromReverseIndex(entries);
+    const directHits = symbolName ? symbolIndex.get(`${abs}::${symbolName}`) || [] : fileIndex.get(abs) || [];
+    const hitsById = new Map();
+    for (const hit of directHits)
+        hitsById.set(hit.id, hit);
+    // BFS the reverse derivedFrom graph from every direct hit's entry id, bounded to
+    // MAX_DERIVED_DEPTH hops — same bound and cycle-guard as checkEntryFreshness's forward
+    // walk, just traversed the other direction (dependents, not dependencies).
+    let frontier = directHits.map((h) => h.id);
+    const visited = new Set(frontier);
+    for (let depth = 0; depth < exports.MAX_DERIVED_DEPTH && frontier.length > 0; depth++) {
+        const next = [];
+        for (const id of frontier) {
+            const dependents = reverseDerived.get(id) || [];
+            for (const depId of dependents) {
+                if (visited.has(depId))
+                    continue;
+                visited.add(depId);
+                next.push(depId);
+                if (!hitsById.has(depId)) {
+                    const entry = entries.get(depId);
+                    if (entry) {
+                        hitsById.set(depId, { id: depId, kind: 'entry', query: entry.query, outcome: entry.outcome, via: 'derived' });
+                    }
+                }
+            }
+        }
+        frontier = next;
+    }
+    const hits = Array.from(hitsById.values());
+    return { hits, failedHits: hits.filter((h) => h.outcome === 'failed') };
+}
+/**
+ * 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 +521,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);
         }
     }
-    return { fresh: staleFiles.length === 0, staleFiles };
+    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, ...(cosmeticChanges.length > 0 ? { cosmeticChanges } : {}) };
 }
 /** Builds the persisted `Claim[]` for an entry from the caller-supplied claim inputs. */
 function buildClaims(inputs) {
@@ -362,14 +566,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 +601,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 +734,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 +791,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 +950,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 +971,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 +1042,52 @@ 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' };
+        });
+    }
+    // ─── Blast radius (Fase E) ──────────────────────────────────────────────────
+    /**
+     * What in the Brain would go stale, directly or transitively, if `filePath`/`symbolName`
+     * changes right now. Called by write tools BEFORE they'd otherwise find out (only on the
+     * next search) — see findBlastRadius for the algorithm and cost.
+     */
+    findBlastRadius(filePath, symbolName) {
+        return findBlastRadius(this.entries, filePath, symbolName);
+    }
     // ─── Stats ────────────────────────────────────────────────────────────────
     getStats() {
         return {