@nxuss/lemma 1.2.4 → 1.3.0

package/dist/esm/utils/StateHashCache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * StateHashCache — reasoning cache keyed to the exact content hash of the files
+ * a question depends on, instead of semantic similarity between questions.
+ *
+ * Unlike a fuzzy/vector cache, a hit here is only returned if every referenced
+ * file's current sha256 matches the hash recorded when the answer was stored.
+ * If any referenced file changed, it's a guaranteed MISS — no stale answers.
+ */
+export interface StateHashEntry {
+    id: string;
+    query: string;
+    answer: string;
+    fileHashes: Record<string, string>;
+    createdAt: number;
+    hits: number;
+}
+export interface StateHashLookupResult {
+    status: 'hit' | 'miss';
+    entry?: StateHashEntry;
+    reason?: string;
+}
+/** Look up a cached answer. Only a hit if every referenced file's hash still matches. */
+export declare function lookupStateHash(projectRoot: string, query: string, filePaths: string[]): StateHashLookupResult;
+/** Store an answer along with the exact hash of every file it depends on. */
+export declare function storeStateHash(projectRoot: string, query: string, answer: string, filePaths: string[]): StateHashEntry;
+//# sourceMappingURL=StateHashCache.d.ts.map

package/dist/esm/utils/StateHashCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateHashCache.d.ts","sourceRoot":"","sources":["../../../src/utils/StateHashCache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AA+CD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EAAE,GAClB,qBAAqB,CAwBvB;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EAAE,GAClB,cAAc,CAmBhB"}

package/dist/esm/utils/StateHashCache.js

@@ -0,0 +1,100 @@
+/**
+ * StateHashCache — reasoning cache keyed to the exact content hash of the files
+ * a question depends on, instead of semantic similarity between questions.
+ *
+ * Unlike a fuzzy/vector cache, a hit here is only returned if every referenced
+ * file's current sha256 matches the hash recorded when the answer was stored.
+ * If any referenced file changed, it's a guaranteed MISS — no stale answers.
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+const CACHE_FILE = '.lemma/state-hash-cache.json';
+function getCachePath(projectRoot) {
+    return path.join(projectRoot, CACHE_FILE);
+}
+function loadCache(projectRoot) {
+    try {
+        const p = getCachePath(projectRoot);
+        if (fs.existsSync(p))
+            return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch { }
+    return { entries: [] };
+}
+function saveCache(projectRoot, data) {
+    try {
+        const dir = path.join(projectRoot, '.lemma');
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(getCachePath(projectRoot), JSON.stringify(data, null, 2), 'utf8');
+    }
+    catch { }
+}
+function sha256(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+function hashFiles(projectRoot, filePaths) {
+    const hashes = {};
+    for (const rel of filePaths) {
+        try {
+            const resolved = path.resolve(projectRoot, rel);
+            if (fs.existsSync(resolved)) {
+                hashes[rel] = sha256(fs.readFileSync(resolved, 'utf8'));
+            }
+            else {
+                hashes[rel] = 'MISSING';
+            }
+        }
+        catch {
+            hashes[rel] = 'ERROR';
+        }
+    }
+    return hashes;
+}
+/** Look up a cached answer. Only a hit if every referenced file's hash still matches. */
+export function lookupStateHash(projectRoot, query, filePaths) {
+    const data = loadCache(projectRoot);
+    const currentHashes = hashFiles(projectRoot, filePaths);
+    const normalizedQuery = query.trim().toLowerCase();
+    const entry = data.entries.find((e) => e.query.trim().toLowerCase() === normalizedQuery);
+    if (!entry)
+        return { status: 'miss', reason: 'no entry for this exact query' };
+    for (const [file, hash] of Object.entries(entry.fileHashes)) {
+        if (currentHashes[file] !== hash) {
+            return { status: 'miss', reason: `file changed since caching: ${file}` };
+        }
+    }
+    // Also fail if the caller now depends on a file that wasn't tracked before —
+    // conservative: only trust the cache if the tracked set covers what's asked now.
+    for (const f of filePaths) {
+        if (!(f in entry.fileHashes)) {
+            return { status: 'miss', reason: `new dependency not covered by cached entry: ${f}` };
+        }
+    }
+    entry.hits += 1;
+    saveCache(projectRoot, data);
+    return { status: 'hit', entry };
+}
+/** Store an answer along with the exact hash of every file it depends on. */
+export function storeStateHash(projectRoot, query, answer, filePaths) {
+    const data = loadCache(projectRoot);
+    const fileHashes = hashFiles(projectRoot, filePaths);
+    const entry = {
+        id: crypto.randomBytes(6).toString('hex'),
+        query,
+        answer,
+        fileHashes,
+        createdAt: Date.now(),
+        hits: 0,
+    };
+    data.entries = data.entries.filter((e) => e.query.trim().toLowerCase() !== query.trim().toLowerCase());
+    data.entries.push(entry);
+    // Bound cache size so it doesn't grow unboundedly.
+    if (data.entries.length > 500) {
+        data.entries = data.entries.slice(data.entries.length - 500);
+    }
+    saveCache(projectRoot, data);
+    return entry;
+}
+//# sourceMappingURL=StateHashCache.js.map

package/dist/esm/utils/StateHashCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateHashCache.js","sourceRoot":"","sources":["../../../src/utils/StateHashCache.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/TokenReceipt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TokenReceipt — an auditable, per-session ledger of how each answer was produced:
+ * exact cache hit, semantic cache hit, file read, or fresh reasoning.
+ *
+ * The point is trust, not just savings: the user (or the model itself) can always
+ * ask "where did that answer actually come from" and get a verifiable trail,
+ * instead of taking a "X% tokens saved" claim on faith.
+ */
+export type ReceiptEventType = 'exact_cache_hit' | 'semantic_cache_hit' | 'file_read' | 'reasoning' | 'tool_call';
+export interface ReceiptEvent {
+    type: ReceiptEventType;
+    label: string;
+    timestamp: number;
+    meta?: Record<string, unknown>;
+}
+export declare function recordReceiptEvent(type: ReceiptEventType, label: string, meta?: Record<string, unknown>): void;
+export interface ReceiptSummary {
+    totalEvents: number;
+    byType: Record<ReceiptEventType, number>;
+    recent: ReceiptEvent[];
+}
+export declare function getReceiptSummary(limit?: number): ReceiptSummary;
+export declare function clearReceiptLedger(): void;
+//# sourceMappingURL=TokenReceipt.d.ts.map

package/dist/esm/utils/TokenReceipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenReceipt.d.ts","sourceRoot":"","sources":["../../../src/utils/TokenReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,oBAAoB,GACpB,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK9G;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,SAAK,GAAG,cAAc,CAc5D;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/esm/utils/TokenReceipt.js

@@ -0,0 +1,36 @@
+/**
+ * TokenReceipt — an auditable, per-session ledger of how each answer was produced:
+ * exact cache hit, semantic cache hit, file read, or fresh reasoning.
+ *
+ * The point is trust, not just savings: the user (or the model itself) can always
+ * ask "where did that answer actually come from" and get a verifiable trail,
+ * instead of taking a "X% tokens saved" claim on faith.
+ */
+const MAX_EVENTS = 2000;
+const sessionLedger = [];
+export function recordReceiptEvent(type, label, meta) {
+    sessionLedger.push({ type, label, timestamp: Date.now(), meta });
+    if (sessionLedger.length > MAX_EVENTS) {
+        sessionLedger.splice(0, sessionLedger.length - MAX_EVENTS);
+    }
+}
+export function getReceiptSummary(limit = 20) {
+    const byType = {
+        exact_cache_hit: 0,
+        semantic_cache_hit: 0,
+        file_read: 0,
+        reasoning: 0,
+        tool_call: 0,
+    };
+    for (const e of sessionLedger)
+        byType[e.type]++;
+    return {
+        totalEvents: sessionLedger.length,
+        byType,
+        recent: sessionLedger.slice(-limit),
+    };
+}
+export function clearReceiptLedger() {
+    sessionLedger.length = 0;
+}
+//# sourceMappingURL=TokenReceipt.js.map

package/dist/esm/utils/TokenReceipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenReceipt.js","sourceRoot":"","sources":["../../../src/utils/TokenReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,UAAU,GAAG,IAAI,CAAC;AAgBxB,MAAM,aAAa,GAAmB,EAAE,CAAC;AAEzC,MAAM,UAAU,kBAAkB,CAAC,IAAsB,EAAE,KAAa,EAAE,IAA8B;IACtG,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,IAAI,aAAa,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACtC,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAQD,MAAM,UAAU,iBAAiB,CAAC,KAAK,GAAG,EAAE;IAC1C,MAAM,MAAM,GAAqC;QAC/C,eAAe,EAAE,CAAC;QAClB,kBAAkB,EAAE,CAAC;QACrB,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,CAAC;KACb,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,aAAa;QAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;IAChD,OAAO;QACL,WAAW,EAAE,aAAa,CAAC,MAAM;QACjC,MAAM;QACN,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxuss/lemma",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Intelligent AI Gateway for IDEs & Agents — Semantic cache, Privacy Firewall, Infrastructure Command Center, and Autonomous Cost-Optimization.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",