pi-mega-compact 0.11.5 → 0.11.6

package/dist/src/config.js

@@ -81,3 +81,20 @@ export function memoryReviewCadence(band, baseInterval) {
         default: return base;
     }
 }
+// ---------------------------------------------------------------------------
+// S57 RAG Suite feature flags — each maps to MEGACOMPACT_* env var, default OFF
+// ---------------------------------------------------------------------------
+function ragFlag(name) {
+    const v = process.env[name];
+    if (v === undefined)
+        return false;
+    return v === "true" || v === "1";
+}
+/** B1: Query reformulation (keyword expansion via embedding neighbors). */
+export const RAG_QUERY_REFORMULATION = () => ragFlag("MEGACOMPACT_QUERY_REFORMULATION");
+/** B2: Tiered recall router (L0 cache → L1 FTS5 → L2 HNSW). */
+export const RAG_TIERED_ROUTER = () => ragFlag("MEGACOMPACT_TIERED_ROUTER");
+/** B3: Recall quality metrics (precision/recall scoring + logging). */
+export const RAG_RECALL_METRICS = () => ragFlag("MEGACOMPACT_RECALL_METRICS");
+/** B4: Memory graph traversal (dashboard-oriented). */
+export const RAG_MEMORY_GRAPH = () => ragFlag("MEGACOMPACT_MEMORY_GRAPH");

package/dist/src/memoryGraph.js

@@ -0,0 +1,299 @@
+/**
+ * memoryGraph.ts — S46 visual memory map: build a graph of graphs.
+ *
+ * Nodes = checkpoints (with optional RAPTOR level annotations).
+ * Edges = temporal adjacency, semantic similarity (cosine above threshold), and
+ *         RAPTOR parent–child links.
+ *
+ * pi-agnostic (no pi runtime types). Zero network calls (PREVENT-PI-004).
+ * Synchronous read-only interface — non-fatal on store errors.
+ *
+ * Re-exports the public types as both MemoryGraph* and shorter aliases
+ * (GraphNode, GraphEdge, GraphMetadata) so dashboard api-contracts can import
+ * from the canonical source.
+ */
+import { getStateDir, normalizeSessionId } from "./store.js";
+import { openStore, decodeEmbedding } from "./store/sqlite/utils.js";
+import { listRaptorNodes } from "./store/sqlite/raptor.js";
+import { Logger } from "./log.js";
+const log = new Logger();
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_SIMILARITY_THRESHOLD = 0.7;
+const DEFAULT_MAX_EDGES_PER_NODE = 4;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build a memory graph from the store.
+ *
+ * Opens the SQLite store, reads all (or session-filtered) checkpoints,
+ * computes cosine similarity edges, temporal edges, and RAPTOR parent edges.
+ * Returns a MemoryGraph or an empty graph on failure (non-fatal).
+ */
+export function buildMemoryGraph(opts = {}) {
+    const { similarityThreshold = DEFAULT_SIMILARITY_THRESHOLD, maxEdgesPerNode = DEFAULT_MAX_EDGES_PER_NODE, sessionId, stateDir = getStateDir(), includeRaptorEdges = true, includeTemporalEdges = true, } = opts;
+    const builtAt = Date.now();
+    try {
+        const nodes = loadNodes(sessionId, stateDir);
+        const nodeIndex = buildNodeIndex(nodes);
+        const edges = [];
+        // Temporal edges: consecutive checkpoints within the same session
+        if (includeTemporalEdges) {
+            edges.push(...buildTemporalEdges(nodes));
+        }
+        // Semantic edges: cosine similarity above threshold
+        edges.push(...buildSemanticEdges(nodes, nodeIndex, similarityThreshold, maxEdgesPerNode));
+        // RAPTOR parent–child edges
+        if (includeRaptorEdges) {
+            edges.push(...buildRaptorEdges(nodes, sessionId, stateDir, nodeIndex));
+        }
+        // Deduplicate edges (keep highest weight for each source-target pair)
+        const dedupedEdges = deduplicateEdges(edges);
+        // Count sessions
+        const sessionSet = new Set();
+        for (const n of nodes) {
+            sessionSet.add(n.sessionId);
+        }
+        const meta = {
+            sessionCount: sessionSet.size,
+            totalCheckpoints: nodes.length,
+            totalEdges: dedupedEdges.length,
+            semanticEdgeCount: dedupedEdges.filter((e) => e.type === "semantic").length,
+            temporalEdgeCount: dedupedEdges.filter((e) => e.type === "temporal").length,
+            raptorEdgeCount: dedupedEdges.filter((e) => e.type === "raptor_parent").length,
+            similarityThresholdUsed: similarityThreshold,
+            builtAt,
+        };
+        return { nodes, edges: dedupedEdges, metadata: meta };
+    }
+    catch (err) {
+        log.warn("buildMemoryGraph failed", { error: String(err) });
+        return {
+            nodes: [],
+            edges: [],
+            metadata: {
+                sessionCount: 0,
+                totalCheckpoints: 0,
+                totalEdges: 0,
+                semanticEdgeCount: 0,
+                temporalEdgeCount: 0,
+                raptorEdgeCount: 0,
+                similarityThresholdUsed: similarityThreshold,
+                builtAt,
+            },
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Node loading
+// ---------------------------------------------------------------------------
+function loadNodes(sessionId, stateDir) {
+    const db = openStore(stateDir);
+    const sql = sessionId
+        ? "SELECT * FROM context_chunks WHERE session_id = ? ORDER BY id ASC"
+        : "SELECT * FROM context_chunks ORDER BY session_id, id ASC";
+    const rows = sessionId
+        ? db.prepare(sql).all(normalizeSessionId(sessionId))
+        : db.prepare(sql).all();
+    return rows.map(rowToGraphNode);
+}
+function rowToGraphNode(row) {
+    const summary = row.summary ?? "";
+    return {
+        id: row.id,
+        sessionId: row.session_id,
+        label: row.id,
+        summaryTruncated: summary.length > 200 ? summary.slice(0, 197) + "..." : summary,
+        tokenEstimate: row.token_estimate ?? 0,
+        timestamp: row.created_at ?? Date.now(),
+        dedupStatus: row.dedup_status ?? undefined,
+        raptorLevel: 0, // enriched below if RAPTOR data exists
+        topicSummary: row.topic_summary ?? undefined,
+        decisionCount: row.key_decisions
+            ? safeJsonCount(row.key_decisions)
+            : 0,
+        textSnippet: summary.length > 200 ? summary.slice(0, 197) + "..." : summary,
+    };
+}
+/** Parse a JSON array stored in a text column and return its length. */
+function safeJsonCount(raw) {
+    if (!raw)
+        return 0;
+    try {
+        const arr = JSON.parse(raw);
+        return Array.isArray(arr) ? arr.length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Node index building
+// ---------------------------------------------------------------------------
+function buildNodeIndex(nodes) {
+    const idx = new Map();
+    nodes.forEach((n, i) => idx.set(n.id, i));
+    return idx;
+}
+// ---------------------------------------------------------------------------
+// Edges: temporal
+// ---------------------------------------------------------------------------
+function buildTemporalEdges(nodes) {
+    const edges = [];
+    if (nodes.length < 2)
+        return edges;
+    let prev = nodes[0];
+    for (let i = 1; i < nodes.length; i++) {
+        const cur = nodes[i];
+        if (cur.sessionId === prev.sessionId) {
+            edges.push({
+                source: prev.id,
+                target: cur.id,
+                weight: 1.0,
+                type: "temporal",
+            });
+        }
+        prev = cur;
+    }
+    return edges;
+}
+// ---------------------------------------------------------------------------
+// Edges: semantic (cosine similarity)
+// ---------------------------------------------------------------------------
+function buildSemanticEdges(nodes, _nodeIndex, threshold, maxPerNode) {
+    if (nodes.length < 2)
+        return [];
+    const db = openStore();
+    // Retrieve embeddings from DB for each node
+    const embeddings = new Map();
+    const placeholders = nodes.map(() => "?").join(",");
+    const ids = nodes.map((n) => n.id);
+    const rows = db
+        .prepare(`SELECT id, embedding_blob FROM context_chunks WHERE id IN (${placeholders})`)
+        .all(...ids);
+    for (const row of rows) {
+        const emb = decodeEmbedding(row.embedding_blob);
+        if (emb.length > 0) {
+            embeddings.set(row.id, emb);
+        }
+    }
+    const edges = [];
+    for (const node of nodes) {
+        const aId = node.id;
+        const aEmb = embeddings.get(aId);
+        if (!aEmb)
+            continue;
+        const candidates = [];
+        for (const other of nodes) {
+            if (other.id === aId)
+                continue;
+            // Skip if already connected via temporal or raptor edge
+            const bEmb = embeddings.get(other.id);
+            if (!bEmb)
+                continue;
+            const sim = cosineSimilarity(aEmb, bEmb);
+            if (sim >= threshold) {
+                candidates.push({ target: other.id, weight: sim });
+            }
+        }
+        // Keep top-K highest-weight semantic neighbors
+        candidates.sort((a, b) => b.weight - a.weight);
+        const top = candidates.slice(0, maxPerNode);
+        for (const c of top) {
+            edges.push({
+                source: aId,
+                target: c.target,
+                weight: c.weight,
+                type: "semantic",
+            });
+        }
+    }
+    return edges;
+}
+// ---------------------------------------------------------------------------
+// Edges: RAPTOR parent–child
+// ---------------------------------------------------------------------------
+function buildRaptorEdges(nodes, sessionId, stateDir, nodeIndex) {
+    const edges = [];
+    try {
+        if (sessionId) {
+            enrichRaptorForSession(sessionId, stateDir, nodeIndex, nodes, edges);
+        }
+        else {
+            // Load all sessions from DB
+            const db = openStore(stateDir);
+            const sessionRows = db
+                .prepare("SELECT DISTINCT session_id FROM raptor_nodes ORDER BY session_id")
+                .all();
+            for (const row of sessionRows) {
+                enrichRaptorForSession(row.session_id, stateDir, nodeIndex, nodes, edges);
+            }
+        }
+    }
+    catch (err) {
+        log.warn("RAPTOR edge build failed (non-fatal)", { error: String(err) });
+    }
+    return edges;
+}
+function enrichRaptorForSession(sessId, stateDir, nodeIndex, nodes, edges) {
+    const raptorNodes = listRaptorNodes(sessId, stateDir);
+    for (const rn of raptorNodes) {
+        const idx = nodeIndex.get(rn.id);
+        if (idx !== undefined) {
+            // Annotate the graph node with the RAPTOR level
+            nodes[idx].raptorLevel = rn.level;
+        }
+        if (!rn.parentId)
+            continue;
+        // Only create edge if both nodes are in the graph
+        if (nodeIndex.has(rn.id) && nodeIndex.has(rn.parentId)) {
+            edges.push({
+                source: rn.id,
+                target: rn.parentId,
+                weight: Math.max(0.1, 1.0 - rn.level * 0.1), // higher levels = weaker link
+                type: "raptor_parent",
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Edge deduplication
+// ---------------------------------------------------------------------------
+function deduplicateEdges(edges) {
+    const seen = new Map();
+    for (const e of edges) {
+        const keyA = `${e.source}|${e.target}`;
+        const keyB = `${e.target}|${e.source}`;
+        const existing = seen.get(keyA) ?? seen.get(keyB);
+        if (!existing) {
+            seen.set(keyA, e);
+        }
+        else if (e.weight > existing.weight) {
+            // Replace with higher-weight edge
+            seen.delete(keyA);
+            seen.delete(keyB);
+            seen.set(keyA, e);
+        }
+    }
+    return Array.from(seen.values());
+}
+// ---------------------------------------------------------------------------
+// Cosine similarity
+// ---------------------------------------------------------------------------
+function cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    if (len === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}

package/dist/src/monitoring.js

@@ -129,3 +129,16 @@ export function defaultMetricsPath(stateDir = STATE_DIR_DEFAULT) {
 export function defaultEventsPath(stateDir = STATE_DIR_DEFAULT) {
     return join(stateDir, "events.log");
 }
+/**
+ * Append a RecallQualityEvent to events.log (best-effort, non-fatal).
+ * Follows the same append-one-JSON-line pattern as logDecision.
+ */
+export function logRecallQuality(path, ev) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, JSON.stringify(ev) + "\n", "utf-8");
+    }
+    catch {
+        /* best-effort — never break the extension */
+    }
+}

package/dist/src/queryExpansion.js

@@ -0,0 +1,163 @@
+/**
+ * queryExpansion.ts — S45 CRAG query expansion via embedding neighbors.
+ *
+ * Expands a query with synonym/related-term variants by finding embedding-
+ * similar checkpoints and extracting their discriminative terms. Fully local:
+ * uses the TrigramEmbedder (shipped default, zero network) and in-process
+ * cosine scan — no LLM call, no external API. PREVENT-PI-004 compliant.
+ *
+ * Pi-agnostic: no pi runtime types or imports from `src/`.
+ */
+import { cosineSimilarity, defaultEmbedder } from "./embedder.js";
+import { listCheckpoints } from "./store/sqlite.js";
+const DEFAULT_MAX_TERMS = 5;
+const DEFAULT_MIN_SIM = 0.3;
+/**
+ * Tokenize text into lowercased alphanumeric terms, filtering stop words.
+ * Internal helper — no export needed outside this module.
+ */
+function tokenizeTerms(text) {
+    const STOP_WORDS = new Set([
+        "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+        "of", "with", "by", "from", "as", "is", "was", "are", "were", "be",
+        "been", "has", "have", "had", "do", "does", "did", "will", "would",
+        "could", "should", "may", "might", "shall", "can", "not", "no", "nor",
+        "so", "if", "then", "than", "that", "this", "these", "those", "it",
+        "its", "i", "me", "my", "we", "our", "you", "your", "he", "she",
+        "they", "them", "their", "what", "which", "who", "whom", "when",
+        "where", "why", "how", "all", "each", "every", "both", "few", "more",
+        "most", "other", "some", "such", "only", "own", "same", "so", "than",
+        "too", "very", "just", "about", "above", "after", "again", "against",
+        "because", "before", "between", "down", "during", "out", "over",
+        "through", "under", "up", "also", "into", "off", "onto", "upon",
+    ]);
+    // Split on non-alphanumeric, lowercase, filter empties and stop words.
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3 && !STOP_WORDS.has(t));
+}
+/**
+ * Compute TF-IDF-like term importance scores for a set of documents.
+ * Returns a Map from term to score (log-frequency within doc * IDF).
+ */
+function termScores(docs) {
+    const docCount = docs.length;
+    if (docCount === 0)
+        return new Map();
+    // Document frequency: how many docs each term appears in.
+    const df = new Map();
+    const docTerms = docs.map((d) => {
+        const terms = tokenizeTerms(d);
+        const unique = new Set(terms);
+        for (const t of unique) {
+            df.set(t, (df.get(t) ?? 0) + 1);
+        }
+        return terms;
+    });
+    // Compute TF-IDF score for each term across all docs:
+    //   score = sum over docs of (tf * idf)
+    //   tf    = term frequency within doc (log-smooth)
+    //   idf   = log(1 + docCount / (1 + docFreq))
+    const scores = new Map();
+    for (let i = 0; i < docTerms.length; i++) {
+        const terms = docTerms[i];
+        const tf = new Map();
+        for (const t of terms)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        for (const [t, count] of tf) {
+            const tfVal = 1 + Math.log10(count);
+            const docFreq = df.get(t) ?? 1;
+            const idf = Math.log10(1 + docCount / (1 + docFreq));
+            scores.set(t, (scores.get(t) ?? 0) + tfVal * idf);
+        }
+    }
+    return scores;
+}
+/**
+ * Expand a query with related terms discovered from embedding-neighbor
+ * checkpoints. Uses TF-IDF term extraction from the most similar checkpoints
+ * to find novel, discriminative terms not already in the query.
+ *
+ * @param query   The original search query.
+ * @param store   VectorStore instance (for checkpoint access + embedder).
+ * @returns       Array of expansion terms (lowercased, max `maxTerms`).
+ */
+export function expandQuery(query, store, opts = {}) {
+    const maxTerms = opts.maxTerms ?? DEFAULT_MAX_TERMS;
+    const minSim = opts.minSimilarity ?? DEFAULT_MIN_SIM;
+    const embedder = opts.embedder ?? store.embedder ?? defaultEmbedder();
+    // Embed the query and scan all checkpoints for nearest neighbors.
+    const qv = embedder.embed(query);
+    const candidates = [];
+    const allSessions = collectSessionIds(store.stateDir);
+    const seen = new Set();
+    for (const sid of allSessions) {
+        const cps = listCheckpoints(sid, store.stateDir);
+        for (const cp of cps) {
+            if (!cp.summary || seen.has(cp.checkpointId))
+                continue;
+            seen.add(cp.checkpointId);
+            const sim = cosineSimilarity(qv, cp.embedding);
+            if (sim >= minSim) {
+                candidates.push({ summary: cp.summary, score: sim });
+            }
+        }
+    }
+    if (candidates.length === 0)
+        return [];
+    // Sort by similarity descending, take the top 20 for term extraction.
+    const topCandidates = candidates
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 20);
+    // Compute TF-IDF scores across the candidate summaries.
+    const docTexts = topCandidates.map((c) => c.summary);
+    const scores = termScores(docTexts);
+    // Filter out query terms: we want NOVEL terms, not the ones already in the query.
+    const queryTerms = new Set(tokenizeTerms(query));
+    // Sort terms by score descending, filter query terms and short/noise terms.
+    const ranked = [...scores.entries()]
+        .filter(([term]) => !queryTerms.has(term))
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, maxTerms)
+        .map(([term]) => term);
+    return ranked;
+}
+/**
+ * Collect unique session IDs that have at least one checkpoint in the store.
+ * Scans the SQLite checkpoint table. Returns an empty array on any error
+ * (non-fatal — query expansion degrades gracefully).
+ */
+function collectSessionIds(stateDir) {
+    try {
+        // We import listCheckpoints per session dynamically. A simpler approach:
+        // scan via a direct SQL query rather than reading every session.
+        // Reuse store/sqlite.ts functions — we can read the sessions table.
+        // Fallback: try listing checkpoints for all known session IDs via
+        // the sessions table.
+        const { db } = loadDb(stateDir);
+        const rows = db
+            .prepare("SELECT DISTINCT session_id FROM checkpoint_epochs ORDER BY session_id")
+            .all();
+        return rows.map((r) => r.session_id);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Lazy-load the SQLite database handle for a given stateDir.
+ * Cached per stateDir to avoid re-opening the file on every call.
+ */
+const _dbCache = new Map();
+function loadDb(stateDir) {
+    const cached = _dbCache.get(stateDir);
+    if (cached)
+        return cached;
+    const { DatabaseSync } = require("node:sqlite");
+    const { join } = require("node:path");
+    const db = new DatabaseSync(join(stateDir, "mega-compact.db"));
+    db.exec("PRAGMA journal_mode=WAL");
+    _dbCache.set(stateDir, { db });
+    return { db };
+}

package/dist/src/queryReformulation/cache.js

@@ -0,0 +1,123 @@
+/**
+ * cache.ts — in-memory LRU cache with TTL for query reformulation results (S43A-8).
+ *
+ * Kept in a separate file to keep queryReformulation.ts under file limits.
+ * Also holds the env-constant defaults and the uncalibrated-constant bookkeeping.
+ */
+// ---------------------------------------------------------------------------
+// Env-Overridable Defaults (sourced from the main file's constants)
+// ---------------------------------------------------------------------------
+function envNum(name, def) {
+    const v = process.env[name];
+    if (v === undefined)
+        return def;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : def;
+}
+export const RRF_K = envNum("MEGACOMPACT_RRF_K", 60);
+export const EXPANSION_NEIGHBOR_COUNT = envNum("MEGACOMPACT_EXPANSION_NEIGHBOR_COUNT", 5);
+export const EXPANSION_TOP_TERMS = envNum("MEGACOMPACT_EXPANSION_TOP_TERMS", 5);
+export const VAGUE_MIN_WORDS = envNum("MEGACOMPACT_VAGUE_MIN_WORDS", 3);
+export const VAGUE_VERY_SHORT_WORDS = envNum("MEGACOMPACT_VAGUE_VERY_SHORT_WORDS", 2);
+export const QUERY_REFORM_CACHE_TTL_SECONDS = envNum("MEGACOMPACT_QUERY_REFORM_CACHE_TTL_SECONDS", 300);
+export const CACHE_MAX_SIZE = envNum("MEGACOMPACT_QUERY_REFORM_CACHE_SIZE", 100);
+const CACHE_STATS_INTERVAL = envNum("MEGACOMPACT_CACHE_STATS_INTERVAL", 100);
+/** Which constant names are uncalibrated (not backed by a paper/benchmark). */
+const UNCALIBRATED_NAMES = new Set([
+    "EXPANSION_NEIGHBOR_COUNT",
+    "EXPANSION_TOP_TERMS",
+    "VAGUE_MIN_WORDS",
+    "VAGUE_VERY_SHORT_WORDS",
+    "QUERY_REFORM_CACHE_TTL_SECONDS",
+]);
+export function computeUncalibrated(opts) {
+    const out = [];
+    if (opts.neighborCount === EXPANSION_NEIGHBOR_COUNT && UNCALIBRATED_NAMES.has("EXPANSION_NEIGHBOR_COUNT")) {
+        out.push("EXPANSION_NEIGHBOR_COUNT");
+    }
+    if (opts.topTerms === EXPANSION_TOP_TERMS && UNCALIBRATED_NAMES.has("EXPANSION_TOP_TERMS")) {
+        out.push("EXPANSION_TOP_TERMS");
+    }
+    if (opts.vagueMinWords === VAGUE_MIN_WORDS && UNCALIBRATED_NAMES.has("VAGUE_MIN_WORDS")) {
+        out.push("VAGUE_MIN_WORDS");
+    }
+    if (opts.vagueVeryShortWords === VAGUE_VERY_SHORT_WORDS && UNCALIBRATED_NAMES.has("VAGUE_VERY_SHORT_WORDS")) {
+        out.push("VAGUE_VERY_SHORT_WORDS");
+    }
+    if (opts.cacheTtlSeconds === QUERY_REFORM_CACHE_TTL_SECONDS && UNCALIBRATED_NAMES.has("QUERY_REFORM_CACHE_TTL_SECONDS")) {
+        out.push("QUERY_REFORM_CACHE_TTL_SECONDS");
+    }
+    return out;
+}
+const QUERY_CACHE = new Map();
+let cacheHits = 0;
+let cacheMisses = 0;
+let cacheEvictions = 0;
+let cacheCounterAtLastLog = 0;
+/** Read (and reset) cache stats. Used by the logger for periodic reporting. */
+export function readCacheStats() {
+    const out = { hits: cacheHits, misses: cacheMisses, evictions: cacheEvictions };
+    // Prevent unbounded growth of the delta-tracking state
+    cacheHits = 0;
+    cacheMisses = 0;
+    cacheEvictions = 0;
+    return out;
+}
+export function cacheGet(query, ttlMs) {
+    const entry = QUERY_CACHE.get(query);
+    if (!entry) {
+        cacheMisses++;
+        return undefined;
+    }
+    if (Date.now() - entry.cachedAt > ttlMs) {
+        QUERY_CACHE.delete(query);
+        cacheEvictions++;
+        cacheMisses++;
+        return undefined;
+    }
+    cacheHits++;
+    return { ...entry.result, fromCache: true };
+}
+export function cacheSet(query, result) {
+    // Evict oldest if over capacity
+    if (QUERY_CACHE.size >= CACHE_MAX_SIZE) {
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of QUERY_CACHE) {
+            if (entry.cachedAt < oldestTime) {
+                oldestTime = entry.cachedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            QUERY_CACHE.delete(oldestKey);
+            cacheEvictions++;
+        }
+    }
+    QUERY_CACHE.set(query, {
+        result: { ...result, fromCache: false },
+        cachedAt: Date.now(),
+    });
+}
+function logCacheStats(log) {
+    // Use the stable readCacheStats + reset
+    const stats = readCacheStats();
+    const total = stats.hits + stats.misses;
+    if (total === 0)
+        return;
+    log.info("query_reformulation_cache_stats", {
+        hits: stats.hits,
+        misses: stats.misses,
+        evictions: stats.evictions,
+        hitRate: total > 0 ? stats.hits / total : 0,
+    });
+}
+export function maybeLogCacheStats(log) {
+    if (!log)
+        return;
+    const total = cacheHits + cacheMisses;
+    if (total - cacheCounterAtLastLog < CACHE_STATS_INTERVAL)
+        return;
+    cacheCounterAtLastLog = total;
+    logCacheStats(log);
+}

package/dist/src/queryReformulation/rrf.js

@@ -0,0 +1,29 @@
+/**
+ * rrf.ts — Reciprocal Rank Fusion (RRF) for merging ranked lists (S43A-7).
+ *
+ * Pure function: takes multiple ranked lists and returns a single fused ranking
+ * using the standard RRF formula.
+ *
+ * Reference: Cormack, G.V., Clarke, C.L.A., Buettcher, S. "Reciprocal Rank
+ * Fusion Outperforms Condorcet and Individual Rank Learning Methods."
+ * SIGIR 2009.
+ */
+/**
+ * Reciprocal Rank Fusion — merge multiple ranked lists into a single score.
+ * Uses the standard RRF formula: score(id) = sum(1 / (k + rank_i(id))).
+ *
+ * k defaults to 60 — the canonical value from Cormack et al. 2009.
+ * Higher k reduces the impact of high rankings; lower k gives more weight to
+ * top-ranked items.
+ */
+export function reciprocalRankFusion(lists, k = 60) {
+    const scores = new Map();
+    for (const list of lists) {
+        for (const item of list) {
+            scores.set(item.id, (scores.get(item.id) ?? 0) + 1 / (k + item.rank));
+        }
+    }
+    return [...scores.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score);
+}