@massa-ai/core 1.2.1

package/dist/services/search/query-understanding.js

@@ -0,0 +1,281 @@
+/**
+ * Query Understanding (Phase 2, plan item 4).
+ *
+ * Expands the user's query before the vector/keyword fan-out:
+ *   1. `rewriteQuery` — LLM produces structured `{ expansions, keywords }`
+ *      via `llmObject` + a zod schema (rejects malformed/empty output).
+ *   2. `hyde` — LLM produces a hypothetical implementation paragraph, which
+ *      is then **embedded with the existing EmbeddingService** (no new
+ *      provider spawned) and returned as an extra vector-query stream.
+ *
+ * Contract (cross-cutting §1 + spec NF1):
+ *   - Default-off via `config.search.queryUnderstanding.enabled`.
+ *   - Silent degradation: on any LLM throw / timeout / disabled, `understand()`
+ *     returns `null` → caller falls through to the original 2-stream search.
+ *     NEVER blocks search, NEVER throws to the caller.
+ *   - HyDE's embed call runs ONLY after the LLM step succeeds (no wasted work).
+ *
+ * Pure over its inputs + the injected `llm` handle + the injected `embedFn`,
+ * so tests inject fakes without touching config or network.
+ */
+import { z } from "zod";
+import { config, logger } from "@massa-ai/shared";
+import { sanitizeFTS5Query } from "@massa-ai/shared";
+import { llm as llmHandle } from "../memory/llm-client.js";
+import { EmbeddingService } from "../embeddings/index.js";
+// ─── Zod schema (R1, P2-REWRITE-03) ────────────────────────────────────────────
+/** Non-empty arrays, bounded length. `llmObject` returns `{ok:false}` on zod failure. */
+export const QueryRewriteSchema = z.object({
+    expansions: z.array(z.string().min(1)).min(1).max(8),
+    keywords: z.array(z.string().min(1)).min(1).max(12),
+});
+// ─── Prompt templates ─────────────────────────────────────────────────────────
+const REWRITE_SYSTEM = "You expand a search query for a code-knowledge retrieval system. " +
+    "Return ONLY a JSON object with two non-empty string arrays: " +
+    "`expansions` (1-8 paraphrases / synonym phrasings of the query) and " +
+    "`keywords` (1-12 distinctive terms likely present in the target document). " +
+    "No prose, no markdown.";
+function rewritePrompt(query) {
+    return `Query: ${query}\nReturn the JSON object now.`;
+}
+const HYDE_SYSTEM = "You write a hypothetical implementation paragraph that a code-knowledge " +
+    "search system will embed and match against real documents. Write ONE " +
+    "concise paragraph (3-6 sentences) of plausible implementation detail " +
+    "(types, function signatures, control flow) that a relevant document would " +
+    "contain. No preamble, no markdown.";
+function hydePrompt(query) {
+    return `Query: ${query}\nWrite the hypothetical implementation paragraph.`;
+}
+// ─── Standalone fns (unit-testable with a fake surface) ───────────────────────
+/**
+ * Rewrite the query into structured expansions + keywords. Returns `null`
+ * when the LLM is disabled, times out, throws, or returns zod-invalid output
+ * (P2-REWRITE-01/02/03). Never throws.
+ */
+export async function rewriteQuery(query, surface, opts = {}) {
+    const res = await surface.object(rewritePrompt(query), QueryRewriteSchema, {
+        system: REWRITE_SYSTEM,
+        timeoutMs: opts.timeoutMs,
+    });
+    if (!res.ok || !res.value)
+        return null;
+    // Defensive: schema guarantees non-empty arrays, but double-check in case a
+    // future schema relaxation lets empties through.
+    if (!Array.isArray(res.value.expansions) ||
+        res.value.expansions.length === 0 ||
+        !Array.isArray(res.value.keywords) ||
+        res.value.keywords.length === 0) {
+        return null;
+    }
+    return res.value;
+}
+/**
+ * Generate a hypothetical implementation paragraph and embed it. The embed
+ * call runs ONLY if the LLM step succeeded (P2-HYDE-02). Uses the **existing**
+ * EmbeddingService via the injected `embedFn` (P2-HYDE-03). Returns `null` on
+ * any failure; never throws.
+ */
+export async function hyde(query, surface, embedFn, opts = {}) {
+    const text = await surface.complete(hydePrompt(query), {
+        system: HYDE_SYSTEM,
+        timeoutMs: opts.timeoutMs,
+    });
+    if (!text.ok || !text.value || text.value.trim().length === 0) {
+        // LLM disabled / timed out / threw → do NOT call embedFn (no wasted work).
+        return null;
+    }
+    try {
+        const vec = await embedFn(text.value);
+        if (!Array.isArray(vec) || vec.length === 0)
+            return null;
+        return vec;
+    }
+    catch (e) {
+        // Embeddings provider unavailable (e.g. Ollama down) → skip HyDE.
+        logger.warn("hyde embed failed — skipping HyDE stream", {
+            error: e.message,
+        });
+        return null;
+    }
+}
+class QueryUnderstandingCache {
+    store = new Map();
+    ttlMs;
+    maxSize;
+    constructor(ttlMs, maxSize) {
+        this.ttlMs = ttlMs;
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() >= entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        // Evict the entry with the earliest expiresAt when over the cap.
+        // (TTL-based eviction rather than true LRU — no new dependency, per spec.)
+        if (this.store.size >= this.maxSize && !this.store.has(key)) {
+            let oldestKey = null;
+            let oldestExpiry = Infinity;
+            for (const [k, e] of this.store) {
+                if (e.expiresAt < oldestExpiry) {
+                    oldestExpiry = e.expiresAt;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey !== null)
+                this.store.delete(oldestKey);
+        }
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    clear() {
+        this.store.clear();
+    }
+    /**
+     * Drop only entries scoped to this projectId. Keys are `${projectId}::${query}`
+     * (see QueryUnderstandingService.run); match the projectId prefix so a
+     * project rename/merge cannot serve stale rewrite/HyDE state. Keeps unrelated
+     * project entries live.
+     */
+    invalidateProject(projectId) {
+        const prefix = `${projectId}::`;
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix))
+                this.store.delete(key);
+        }
+    }
+    /** @internal — for tests. */
+    get size() {
+        return this.store.size;
+    }
+}
+// ─── Service ──────────────────────────────────────────────────────────────────
+/**
+ * Orchestrates rewrite + HyDE behind a per-`(projectId, query)` cache.
+ * `understand()` returns `null` on any failure path → caller falls through.
+ */
+export class QueryUnderstandingService {
+    llmSurface;
+    embedFn;
+    cache;
+    /** Capture the last-call telemetry for tests/observability. */
+    lastHydeUsed = false;
+    constructor(opts = {}) {
+        this.llmSurface = opts.llmSurface ?? llmHandle;
+        // Reuse the existing EmbeddingService singleton (instantiated once here;
+        // no new provider spawned). Injectable for tests.
+        this.embedFn =
+            opts.embedFn ??
+                ((text) => getEmbeddingSingleton().embed(text));
+        // Defensive against partial/mocked config (the shared-config mock is
+        // process-wide and omits the queryUnderstanding block in some test files).
+        const qu = readQueryUnderstandingConfig();
+        this.cache = new QueryUnderstandingCache(opts.cacheTtlMs ?? qu.cacheTtlMs, opts.cacheMaxSize ?? qu.cacheMaxSize);
+    }
+    /**
+     * Run rewrite + HyDE for `(query, projectId)`. Cached per the configured TTL.
+     * Returns `null` on any failure / disabled → caller's original search path.
+     * Never throws.
+     */
+    async understand(query, projectId) {
+        const trimmed = query?.trim();
+        if (!trimmed)
+            return null;
+        const key = `${projectId}::${trimmed}`;
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.lastHydeUsed = cached.hydeVector !== null;
+            return cached;
+        }
+        const qu = readQueryUnderstandingConfig();
+        const timeoutMs = readLlmTimeoutMs();
+        const rewrite = await rewriteQuery(trimmed, this.llmSurface, { timeoutMs });
+        if (!rewrite) {
+            // Rewrite is the gate: if it failed, no point running HyDE either.
+            this.lastHydeUsed = false;
+            return null;
+        }
+        let hydeVector = null;
+        if (qu.hydeEnabled !== false) {
+            hydeVector = await hyde(trimmed, this.llmSurface, this.embedFn, {
+                timeoutMs,
+            });
+        }
+        this.lastHydeUsed = hydeVector !== null;
+        const result = {
+            expansions: rewrite.expansions,
+            keywords: rewrite.keywords,
+            hydeVector,
+        };
+        this.cache.set(key, result);
+        return result;
+    }
+    /** @internal — clear cache between tests. */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Drop only rewrite/HyDE entries for this projectId (post-commit invalidator
+     * hook for project rename/merge). See QueryUnderstandingCache.invalidateProject.
+     */
+    invalidateProject(projectId) {
+        this.cache.invalidateProject(projectId);
+    }
+}
+// ─── FTS5 query construction (design §3.1) ────────────────────────────────────
+/**
+ * Build a quoted FTS5 OR query from the original query + keywords. Each term
+ * is FTS5-quoted (internal `"` doubled) and joined with `OR` so the keyword
+ * search treats them as a recall-broadening disjunction. Mirrors the per-term
+ * quoting that `sanitizeFTS5Query` applies, but operates on already-distinct
+ * terms (calling sanitizeFTS5Query on the composed string would re-split the
+ * quoted phrases). Returns a sanitized form of the original query when no
+ * keywords survive cleaning.
+ */
+export function buildRewrittenFTSQuery(query, keywords) {
+    const quoteTerm = (t) => `"${t.replace(/"/g, '""')}"`;
+    const parts = [];
+    const q = query?.trim();
+    if (q)
+        parts.push(quoteTerm(q));
+    for (const kw of keywords) {
+        const clean = kw.trim();
+        if (clean)
+            parts.push(quoteTerm(clean));
+    }
+    if (parts.length === 0)
+        return sanitizeFTS5Query(query);
+    return parts.join(" OR ");
+}
+// ─── Shared EmbeddingService singleton (lazy) ─────────────────────────────────
+// One instance reused by all QueryUnderstandingService consumers — mirrors how
+// PostgresVectorStore instantiates its own. Do NOT spawn extra providers.
+let embeddingSingleton;
+function getEmbeddingSingleton() {
+    if (!embeddingSingleton)
+        embeddingSingleton = new EmbeddingService();
+    return embeddingSingleton;
+}
+// ─── Defensive config readers ─────────────────────────────────────────────────
+// `bun mock.module("@massa-ai/shared")` is process-wide (Phase-1 finding) and
+// some test files' mock omits the queryUnderstanding block. These readers fall
+// back to the spec defaults so the constructor never throws under a mock.
+function readQueryUnderstandingConfig() {
+    const qu = config.get("search")?.queryUnderstanding;
+    return {
+        enabled: qu?.enabled === true,
+        hydeEnabled: qu?.hydeEnabled !== false,
+        cacheTtlMs: qu?.cacheTtlMs ?? 300_000,
+        cacheMaxSize: qu?.cacheMaxSize ?? 256,
+    };
+}
+function readLlmTimeoutMs() {
+    const llmCfg = config.get("llm") ?? {};
+    return typeof llmCfg.timeoutMs === "number" ? llmCfg.timeoutMs : 30000;
+}
+//# sourceMappingURL=query-understanding.js.map

package/dist/services/search/query-understanding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-understanding.js","sourceRoot":"","sources":["../../../src/services/search/query-understanding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,kFAAkF;AAElF,yFAAyF;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;CACpD,CAAC,CAAC;AAgCH,iFAAiF;AAEjF,MAAM,cAAc,GAClB,mEAAmE;IACnE,8DAA8D;IAC9D,sEAAsE;IACtE,6EAA6E;IAC7E,wBAAwB,CAAC;AAE3B,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,UAAU,KAAK,+BAA+B,CAAC;AACxD,CAAC;AAED,MAAM,WAAW,GACf,0EAA0E;IAC1E,uEAAuE;IACvE,uEAAuE;IACvE,4EAA4E;IAC5E,oCAAoC,CAAC;AAEvC,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,UAAU,KAAK,oDAAoD,CAAC;AAC7E,CAAC;AAED,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,OAAwB,EACxB,OAA+B,EAAE;IAEjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,kBAAkB,EAAE;QACzE,MAAM,EAAE,cAAc;QACtB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACvC,4EAA4E;IAC5E,iDAAiD;IACjD,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC;QACpC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QACjC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC;QAClC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,KAAa,EACb,OAAwB,EACxB,OAAgB,EAChB,OAA+B,EAAE;IAEjC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE;QACrD,MAAM,EAAE,WAAW;QACnB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,2EAA2E;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACzD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,kEAAkE;QAClE,MAAM,CAAC,IAAI,CAAC,0CAA0C,EAAE;YACtD,KAAK,EAAG,CAAW,CAAC,OAAO;SAC5B,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AASD,MAAM,uBAAuB;IACnB,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,KAAK,CAAS;IACd,OAAO,CAAS;IAExB,YAAY,KAAa,EAAE,OAAe;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAA+B;QAC9C,iEAAiE;QACjE,2EAA2E;QAC3E,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5D,IAAI,SAAS,GAAkB,IAAI,CAAC;YACpC,IAAI,YAAY,GAAG,QAAQ,CAAC;YAC5B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAChC,IAAI,CAAC,CAAC,SAAS,GAAG,YAAY,EAAE,CAAC;oBAC/B,YAAY,GAAG,CAAC,CAAC,SAAS,CAAC;oBAC3B,SAAS,GAAG,CAAC,CAAC;gBAChB,CAAC;YACH,CAAC;YACD,IAAI,SAAS,KAAK,IAAI;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,SAAiB;QACjC,MAAM,MAAM,GAAG,GAAG,SAAS,IAAI,CAAC;QAChC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,6BAA6B;IAC7B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,OAAO,yBAAyB;IACnB,UAAU,CAAkB;IAC5B,OAAO,CAAU;IACjB,KAAK,CAA0B;IAChD,+DAA+D;IAC/D,YAAY,GAAY,KAAK,CAAC;IAE9B,YAAY,OAKR,EAAE;QACJ,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAK,SAAwC,CAAC;QAC/E,yEAAyE;QACzE,kDAAkD;QAClD,IAAI,CAAC,OAAO;YACV,IAAI,CAAC,OAAO;gBACZ,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,qBAAqB,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1D,qEAAqE;QACrE,2EAA2E;QAC3E,MAAM,EAAE,GAAG,4BAA4B,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,uBAAuB,CACtC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,UAAU,EAChC,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC,YAAY,CACrC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CACd,KAAa,EACb,SAAiB;QAEjB,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAE1B,MAAM,GAAG,GAAG,GAAG,SAAS,KAAK,OAAO,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC;YAC/C,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,EAAE,GAAG,4BAA4B,EAAE,CAAC;QAC1C,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;QAErC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5E,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,mEAAmE;YACnE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,UAAU,GAAoB,IAAI,CAAC;QACvC,IAAI,EAAE,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;YAC7B,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE;gBAC9D,SAAS;aACV,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,UAAU,KAAK,IAAI,CAAC;QAExC,MAAM,MAAM,GAA6B;YACvC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,UAAU;SACX,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,6CAA6C;IAC7C,UAAU;QACR,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,SAAiB;QACjC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAa,EACb,QAAkB;IAElB,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;IACtE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IACxB,IAAI,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,iFAAiF;AACjF,+EAA+E;AAC/E,0EAA0E;AAC1E,IAAI,kBAAoC,CAAC;AACzC,SAAS,qBAAqB;IAC5B,IAAI,CAAC,kBAAkB;QAAE,kBAAkB,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACrE,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED,iFAAiF;AACjF,8EAA8E;AAC9E,+EAA+E;AAC/E,0EAA0E;AAC1E,SAAS,4BAA4B;IACnC,MAAM,EAAE,GAAI,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAS,EAAE,kBAAkB,CAAC;IAC7D,OAAO;QACL,OAAO,EAAE,EAAE,EAAE,OAAO,KAAK,IAAI;QAC7B,WAAW,EAAE,EAAE,EAAE,WAAW,KAAK,KAAK;QACtC,UAAU,EAAE,EAAE,EAAE,UAAU,IAAI,OAAO;QACrC,YAAY,EAAE,EAAE,EAAE,YAAY,IAAI,GAAG;KACtC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,MAAM,GAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAS,IAAI,EAAE,CAAC;IAChD,OAAO,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACzE,CAAC"}

package/dist/services/search/reranker.d.ts

@@ -0,0 +1,59 @@
+/**
+ * LLM-Judge Reranker (Phase 7a, plan item 7a).
+ *
+ * Re-scores the top-K (`search.rerank.rerankWindow`, default 50) results of a
+ * fused/centrality-boosted list via a single `llmObject` call with a strict zod
+ * schema. The returned `rankedIds` is a permutation guide:
+ *   - ids present in both verdict + window → placed in LLM order.
+ *   - ids missing from the verdict → appended in their original order.
+ *   - duplicate ids in the verdict → first occurrence wins, rest dropped.
+ *
+ * Contract (cross-cutting §1 + spec R7A-02):
+ *   - Default-off via `config.search.rerank.enabled`.
+ *   - Silent degradation: on `!isLlmEnabled()`, `{ok:false}`, or any throw,
+ *     returns the input list VERBATIM (no re-order, no drop). Never throws to
+ *     the caller (SearchController). Logged at warn.
+ *   - Only the top-K window is re-ordered; the tail (rank > window) is
+ *     concatenated unchanged. Final list length == input length (rerank never
+ *     drops results).
+ *
+ * Pure over inputs + the injected LLM surface, so tests inject fakes without
+ * touching config or network (design.md §7).
+ */
+import { z } from "zod";
+import type { SearchResult } from "@massa-ai/shared";
+import type { QueryLlmSurface } from "./query-understanding.js";
+/** The LLM returns an ordered id list. Non-empty array of strings. */
+export declare const RerankVerdictSchema: z.ZodObject<{
+    rankedIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type RerankVerdict = z.infer<typeof RerankVerdictSchema>;
+/**
+ * LLM-judge reranker. Stateless; the `llm` surface is injectable for tests.
+ */
+export declare class LLMJudgeReranker {
+    private readonly llm;
+    constructor(llm?: QueryLlmSurface);
+    /**
+     * Re-order the top-K (`window`) of `results` per the LLM verdict.
+     *
+     * - When `!isLlmEnabled()` OR the feature is off OR `window <= 0`, returns
+     *   `results` verbatim.
+     * - On `{ok:false}` or throw, returns `results` verbatim (logged at warn).
+     * - Empty input → empty output (no-op).
+     *
+     * `window` defaults to `config.search.rerank.rerankWindow` (50). Callers may
+     * pass an explicit value for tests / tighter budgets.
+     */
+    rerank(query: string, results: SearchResult[], window?: number): Promise<SearchResult[]>;
+}
+/**
+ * Apply the verdict permutation to the head:
+ *   - ids in the verdict AND in head → placed in verdict order.
+ *   - ids in the verdict but NOT in head → ignored.
+ *   - duplicate ids in the verdict → first occurrence wins.
+ *   - head ids missing from the verdict → appended in original order.
+ * Result length == head.length (no drops, no additions).
+ */
+export declare function applyVerdict(head: SearchResult[], rankedIds: string[]): SearchResult[];
+//# sourceMappingURL=reranker.d.ts.map

package/dist/services/search/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/services/search/reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAKhE,sEAAsE;AACtE,eAAO,MAAM,mBAAmB;;iBAE9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAUhE;;GAEG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,eAAkC;IAEpE;;;;;;;;;;OAUG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EAAE,EACvB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,EAAE,CAAC;CA4C3B;AAsCD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,CAqBtF"}

package/dist/services/search/reranker.js

@@ -0,0 +1,156 @@
+/**
+ * LLM-Judge Reranker (Phase 7a, plan item 7a).
+ *
+ * Re-scores the top-K (`search.rerank.rerankWindow`, default 50) results of a
+ * fused/centrality-boosted list via a single `llmObject` call with a strict zod
+ * schema. The returned `rankedIds` is a permutation guide:
+ *   - ids present in both verdict + window → placed in LLM order.
+ *   - ids missing from the verdict → appended in their original order.
+ *   - duplicate ids in the verdict → first occurrence wins, rest dropped.
+ *
+ * Contract (cross-cutting §1 + spec R7A-02):
+ *   - Default-off via `config.search.rerank.enabled`.
+ *   - Silent degradation: on `!isLlmEnabled()`, `{ok:false}`, or any throw,
+ *     returns the input list VERBATIM (no re-order, no drop). Never throws to
+ *     the caller (SearchController). Logged at warn.
+ *   - Only the top-K window is re-ordered; the tail (rank > window) is
+ *     concatenated unchanged. Final list length == input length (rerank never
+ *     drops results).
+ *
+ * Pure over inputs + the injected LLM surface, so tests inject fakes without
+ * touching config or network (design.md §7).
+ */
+import { z } from "zod";
+import { config, logger } from "@massa-ai/shared";
+import { llm as defaultLlmHandle } from "../memory/llm-client.js";
+// ─── Zod schema ────────────────────────────────────────────────────────────────
+/** The LLM returns an ordered id list. Non-empty array of strings. */
+export const RerankVerdictSchema = z.object({
+    rankedIds: z.array(z.string().min(1)).min(1),
+});
+// ─── Defaults ──────────────────────────────────────────────────────────────────
+const DEFAULT_RERANK_WINDOW = 50;
+/** Truncate each candidate's content in the prompt to bound prompt size. */
+const CONTENT_TRUNCATE_CHARS = 500;
+// ─── Public API ────────────────────────────────────────────────────────────────
+/**
+ * LLM-judge reranker. Stateless; the `llm` surface is injectable for tests.
+ */
+export class LLMJudgeReranker {
+    llm;
+    constructor(llm = defaultLlmHandle) {
+        this.llm = llm;
+    }
+    /**
+     * Re-order the top-K (`window`) of `results` per the LLM verdict.
+     *
+     * - When `!isLlmEnabled()` OR the feature is off OR `window <= 0`, returns
+     *   `results` verbatim.
+     * - On `{ok:false}` or throw, returns `results` verbatim (logged at warn).
+     * - Empty input → empty output (no-op).
+     *
+     * `window` defaults to `config.search.rerank.rerankWindow` (50). Callers may
+     * pass an explicit value for tests / tighter budgets.
+     */
+    async rerank(query, results, window) {
+        // Degradation: empty list or disabled → verbatim.
+        if (results.length === 0)
+            return results;
+        const searchCfg = config.get("search");
+        const rerankCfg = searchCfg.rerank;
+        if (!rerankCfg?.enabled)
+            return results;
+        if (!this.llm.isEnabled())
+            return results;
+        const win = Math.max(1, window ?? rerankWindowFromConfig() ?? DEFAULT_RERANK_WINDOW);
+        // If window >= list, the whole list is the re-order scope.
+        const k = Math.min(win, results.length);
+        const head = results.slice(0, k);
+        const tail = results.slice(k);
+        const prompt = buildPrompt(query, head);
+        let verdict;
+        try {
+            const res = await this.llm.object(prompt, RerankVerdictSchema, { modelRole: "code" });
+            verdict = res.ok ? (res.value ?? null) : null;
+        }
+        catch (e) {
+            logger.warn("LLMJudgeReranker threw — degrading to input order", {
+                query,
+                error: e.message,
+            });
+            return results;
+        }
+        if (!verdict) {
+            logger.warn("LLMJudgeReranker got {ok:false} — degrading to input order", {
+                query,
+            });
+            return results;
+        }
+        const reorderedHead = applyVerdict(head, verdict.rankedIds);
+        return [...reorderedHead, ...tail];
+    }
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+function rerankWindowFromConfig() {
+    const searchCfg = config.get("search");
+    const w = searchCfg.rerank?.rerankWindow;
+    return typeof w === "number" && Number.isFinite(w) ? w : undefined;
+}
+/**
+ * Build the judge prompt: the query + the top-K candidates
+ * `{id, content (truncated), score}`. Asks for a strict re-order.
+ */
+function buildPrompt(query, head) {
+    const candidates = head
+        .map((r, i) => {
+        const content = (r.content ?? "").slice(0, CONTENT_TRUNCATE_CHARS);
+        const score = typeof r.score === "number" ? r.score.toFixed(4) : "?";
+        return `${i + 1}. id=${r.id} score=${score}\n${content}`;
+    })
+        .join("\n\n");
+    return [
+        "You are a retrieval reranker. Re-order the candidate code snippets by",
+        "relevance to the user's query. Return ONLY a JSON object",
+        '{"rankedIds": [string, ...]} listing the candidate ids best-first.',
+        "Every candidate id must appear exactly once. Do not invent ids.",
+        "",
+        `Query: ${query}`,
+        "",
+        "Candidates:",
+        candidates,
+    ].join("\n");
+}
+/**
+ * Apply the verdict permutation to the head:
+ *   - ids in the verdict AND in head → placed in verdict order.
+ *   - ids in the verdict but NOT in head → ignored.
+ *   - duplicate ids in the verdict → first occurrence wins.
+ *   - head ids missing from the verdict → appended in original order.
+ * Result length == head.length (no drops, no additions).
+ */
+export function applyVerdict(head, rankedIds) {
+    const byId = new Map();
+    for (const r of head)
+        if (!byId.has(r.id))
+            byId.set(r.id, r);
+    const out = [];
+    const seen = new Set();
+    for (const id of rankedIds) {
+        if (seen.has(id))
+            continue; // dedup: first occurrence wins
+        const r = byId.get(id);
+        if (!r)
+            continue; // verdict id not in head → ignore
+        out.push(r);
+        seen.add(id);
+    }
+    // Append any head ids the verdict omitted, in original head order.
+    for (const r of head) {
+        if (!seen.has(r.id)) {
+            out.push(r);
+            seen.add(r.id);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=reranker.js.map

package/dist/services/search/reranker.js.map

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

package/dist/services/search/rlm-admin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * rlm-admin — admin/stats delegates for ContextualSearchRLM.
+ *
+ * Extracted (M14 Phase 3, T3.3) from contextual-search-rlm.ts. Behavior is
+ * byte-preserved: bodies moved verbatim with `this` → `rlm`.
+ */
+import { SearchAnalytics } from "./search-analytics.js";
+import type { SearchAnalyticsPg } from "./search-analytics-pg.js";
+import type { ContextualSearchRLM } from "./contextual-search-rlm.js";
+export declare function clearProjectIndexImpl(rlm: ContextualSearchRLM, projectId: string): Promise<{
+    deleted: number;
+}>;
+export declare function getProjectStatsImpl(rlm: ContextualSearchRLM, projectId: string): Promise<{
+    totalDocuments: number;
+    totalSize: number;
+}>;
+export declare function warmupCacheImpl(rlm: ContextualSearchRLM, projectId: string, _projectPath: string, customQueries?: string[]): Promise<{
+    queriesWarmed: number;
+    errors: number;
+}>;
+export declare function getAnalyticsImpl(rlm: ContextualSearchRLM): SearchAnalytics | SearchAnalyticsPg;
+//# sourceMappingURL=rlm-admin.d.ts.map

package/dist/services/search/rlm-admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rlm-admin.d.ts","sourceRoot":"","sources":["../../../src/services/search/rlm-admin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,mBAAmB,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB9B;AAID,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,mBAAmB,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IACT,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAGD;AAID,wBAAsB,eAAe,CACnC,GAAG,EAAE,mBAAmB,EACxB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAqDpD;AAID,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,mBAAmB,GACvB,eAAe,GAAG,iBAAiB,CAErC"}

package/dist/services/search/rlm-admin.js

@@ -0,0 +1,92 @@
+/**
+ * rlm-admin — admin/stats delegates for ContextualSearchRLM.
+ *
+ * Extracted (M14 Phase 3, T3.3) from contextual-search-rlm.ts. Behavior is
+ * byte-preserved: bodies moved verbatim with `this` → `rlm`.
+ */
+import { logger } from "@massa-ai/shared";
+// ── clearProjectIndex ────────────────────────────────────────────────────────
+export async function clearProjectIndexImpl(rlm, projectId) {
+    await rlm.ensureInitialized();
+    try {
+        const [deleted, keywordDeleted] = await Promise.all([
+            rlm.vectorStore.deleteByProject(projectId),
+            rlm.keywordSearch.deleteByProject(projectId),
+        ]);
+        // Clear associated caches
+        await rlm.searchCache.invalidateProject(projectId);
+        rlm.fileFilterCache.invalidateProject(projectId);
+        logger.info("Project index and caches cleared", {
+            projectId,
+            deleted,
+            keywordDeleted,
+        });
+        return { deleted };
+    }
+    catch (error) {
+        logger.error("Failed to clear project index", error, {
+            projectId,
+        });
+        return { deleted: 0 };
+    }
+}
+// ── getProjectStats ──────────────────────────────────────────────────────────
+export async function getProjectStatsImpl(rlm, projectId) {
+    await rlm.ensureInitialized();
+    return rlm.vectorStore.getStats(projectId);
+}
+// ── warmupCache ──────────────────────────────────────────────────────────────
+export async function warmupCacheImpl(rlm, projectId, _projectPath, customQueries) {
+    await rlm.ensureInitialized();
+    logger.info("Starting cache warmup", { projectId });
+    // Common search patterns based on file types and structure
+    const commonQueries = customQueries || [
+        "authentication",
+        "api endpoints",
+        "database models",
+        "components",
+        "utils",
+        "configuration",
+        "routes",
+        "services",
+        "tests",
+        "types",
+        "interfaces",
+        "error handling",
+        "validation",
+        "middleware",
+        "hooks",
+    ];
+    let queriesWarmed = 0;
+    let errors = 0;
+    // Run searches in background to populate cache
+    for (const query of commonQueries) {
+        try {
+            await rlm.search(query, projectId, {
+                maxResults: 10,
+                minScore: 0.3,
+            });
+            queriesWarmed++;
+            logger.debug("Warmed cache for query", { query, projectId });
+        }
+        catch (error) {
+            logger.error("Failed to warm cache for query", error, {
+                query,
+                projectId,
+            });
+            errors++;
+        }
+    }
+    logger.info("Cache warmup completed", {
+        projectId,
+        queriesWarmed,
+        errors,
+        totalQueries: commonQueries.length,
+    });
+    return { queriesWarmed, errors };
+}
+// ── getAnalytics ─────────────────────────────────────────────────────────────
+export function getAnalyticsImpl(rlm) {
+    return rlm.analytics;
+}
+//# sourceMappingURL=rlm-admin.js.map

package/dist/services/search/rlm-admin.js.map

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