@rubytech/create-maxy-code 0.1.131 → 0.1.138

package/payload/platform/lib/graph-search/dist/query-expansion.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Multi-query expansion via Haiku (Task 308).
+ *
+ * Generates 3-5 paraphrases of the user query so the hybrid pipeline runs
+ * each paraphrase against vector + BM25 in parallel and unions the
+ * candidate sets before fusion. Recovers recall on terse queries where the
+ * embedding's nearest-neighbour is unstable.
+ *
+ * The expansion runs through `@rubytech/oauth-llm` against Claude Haiku —
+ * the same OAuth-bearer path the admin classifiers use; no new SDK
+ * dependency and no Anthropic-API-key path. Cache is in-process, keyed by
+ * (accountId, normalisedQuery, retrievalClass), with a 1-hour TTL.
+ *
+ * Graceful degrade: if the LLM call fails, returns just the original
+ * query. The caller's hybrid pipeline still runs — just on one query
+ * instead of N — so missing paraphrases are a recall regression, not a
+ * fault.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearExpansionCache = clearExpansionCache;
+exports.expandQuery = expandQuery;
+const index_js_1 = require("../../oauth-llm/dist/index.js");
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const HAIKU_MODEL = "claude-haiku-4-5";
+const MAX_PARAPHRASES = 5;
+const cache = new Map();
+function clearExpansionCache() {
+    cache.clear();
+}
+/**
+ * Return `[query, ...paraphrases]` (original always first). On LLM
+ * failure returns `[query]` only and writes a single stderr line so the
+ * operator can see expansion is degrading without breaking search.
+ */
+async function expandQuery(params) {
+    const { query, retrievalClass = "general", accountId = "", useCache = true } = params;
+    const normalised = query.trim().toLowerCase();
+    const cacheKey = `${accountId}::${retrievalClass}::${normalised}`;
+    if (useCache) {
+        const hit = cache.get(cacheKey);
+        if (hit && hit.expiresAt > Date.now()) {
+            return [query, ...hit.expansions];
+        }
+    }
+    const systemPrompt = [
+        "You generate paraphrases of a user query for hybrid graph search.",
+        "Return 3-5 alternative phrasings that preserve the user's intent but vary the surface form (synonyms, word order, entity-vs-attribute framing).",
+        "Do not change the entity names. Do not invent constraints the user did not state.",
+        "Output ONLY a JSON object via the provided tool; never free text.",
+    ].join("\n");
+    const classHint = retrievalClass === "general"
+        ? ""
+        : `The retrieval class is '${retrievalClass}' — tailor paraphrases accordingly.`;
+    const userMessage = [
+        `Original query: ${query}`,
+        classHint,
+    ].filter((s) => s.length > 0).join("\n");
+    const result = await (0, index_js_1.callOauthLlm)({
+        model: HAIKU_MODEL,
+        system: systemPrompt,
+        userMessage,
+        maxTokens: 512,
+        timeoutMs: 15_000,
+        tools: [
+            {
+                name: "emit_paraphrases",
+                description: "Emit 3-5 paraphrases of the user query.",
+                input_schema: {
+                    type: "object",
+                    properties: {
+                        paraphrases: {
+                            type: "array",
+                            items: { type: "string" },
+                            minItems: 3,
+                            maxItems: MAX_PARAPHRASES,
+                        },
+                    },
+                    required: ["paraphrases"],
+                },
+            },
+        ],
+        toolChoiceName: "emit_paraphrases",
+    });
+    if (result.kind !== "ok-tool") {
+        process.stderr.write(`[graph-search:expansion-failed] cause=${result.kind === "fallback" ? result.cause : "unexpected"} query=${query.slice(0, 60).replace(/\s+/g, " ")}\n`);
+        return [query];
+    }
+    const raw = result.input.paraphrases;
+    if (!Array.isArray(raw))
+        return [query];
+    const expansions = raw
+        .filter((p) => typeof p === "string" && p.trim().length > 0)
+        .map((p) => p.trim())
+        .slice(0, MAX_PARAPHRASES);
+    if (useCache) {
+        cache.set(cacheKey, { expansions, expiresAt: Date.now() + CACHE_TTL_MS });
+    }
+    return [query, ...expansions];
+}
+//# sourceMappingURL=query-expansion.js.map

package/payload/platform/lib/graph-search/dist/query-expansion.js.map

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

package/payload/platform/lib/graph-search/dist/route.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Retrieval-class routing (Task 308).
+ *
+ * Consumes the `retrievalClass` field produced by Task 304's
+ * gateway-classifier (landed) and returns a per-class index plan: which
+ * labels to filter to, which fusion weights to favour, and whether to
+ * skip the lookup entirely.
+ *
+ * No new Haiku call here — this module is a pure deterministic mapping
+ * over the gateway's existing classification.
+ */
+export type RetrievalClass = "entity" | "temporal" | "event" | "general" | "none";
+export interface IndexPlan {
+    /** When true, the caller short-circuits and returns no results. */
+    skip: boolean;
+    /** Restrict vector + BM25 to these labels. Undefined means no filter. */
+    labelFilter?: string[];
+    /** Weight on the vector half of the (weighted-sum) fusion. */
+    vectorWeight: number;
+    /** Weight on the BM25 half of the (weighted-sum) fusion. */
+    bm25Weight: number;
+}
+/**
+ * Return the index plan for a retrieval class. Unknown values fall back
+ * to `general` rather than throwing — the routing is a soft hint and the
+ * caller's old behaviour is the safe default.
+ */
+export declare function pickIndexMix(retrievalClass: string | undefined): IndexPlan;
+//# sourceMappingURL=route.d.ts.map

package/payload/platform/lib/graph-search/dist/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,UAAU,GACV,OAAO,GACP,SAAS,GACT,MAAM,CAAC;AAEX,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,IAAI,EAAE,OAAO,CAAC;IACd,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAkC1E"}

package/payload/platform/lib/graph-search/dist/route.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Retrieval-class routing (Task 308).
+ *
+ * Consumes the `retrievalClass` field produced by Task 304's
+ * gateway-classifier (landed) and returns a per-class index plan: which
+ * labels to filter to, which fusion weights to favour, and whether to
+ * skip the lookup entirely.
+ *
+ * No new Haiku call here — this module is a pure deterministic mapping
+ * over the gateway's existing classification.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickIndexMix = pickIndexMix;
+/**
+ * Return the index plan for a retrieval class. Unknown values fall back
+ * to `general` rather than throwing — the routing is a soft hint and the
+ * caller's old behaviour is the safe default.
+ */
+function pickIndexMix(retrievalClass) {
+    switch (retrievalClass) {
+        case "entity":
+            return {
+                skip: false,
+                labelFilter: ["Person", "Company", "Concept"],
+                vectorWeight: 0.85,
+                bm25Weight: 0.15,
+            };
+        case "temporal":
+            return {
+                skip: false,
+                labelFilter: ["Event"],
+                vectorWeight: 0.2,
+                bm25Weight: 0.8,
+            };
+        case "event":
+            return {
+                skip: false,
+                labelFilter: ["Event"],
+                vectorWeight: 0,
+                bm25Weight: 1,
+            };
+        case "none":
+            return { skip: true, vectorWeight: 0, bm25Weight: 0 };
+        case "general":
+        default:
+            if (retrievalClass && retrievalClass !== "general") {
+                process.stderr.write(`[graph-search:unknown-class] rc=${retrievalClass} fallback=general\n`);
+            }
+            return { skip: false, vectorWeight: 0.7, bm25Weight: 0.3 };
+    }
+}
+//# sourceMappingURL=route.js.map

package/payload/platform/lib/graph-search/dist/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAyBH,oCAkCC;AAvCD;;;;GAIG;AACH,SAAgB,YAAY,CAAC,cAAkC;IAC7D,QAAQ,cAAc,EAAE,CAAC;QACvB,KAAK,QAAQ;YACX,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,WAAW,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;gBAC7C,YAAY,EAAE,IAAI;gBAClB,UAAU,EAAE,IAAI;aACjB,CAAC;QACJ,KAAK,UAAU;YACb,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,WAAW,EAAE,CAAC,OAAO,CAAC;gBACtB,YAAY,EAAE,GAAG;gBACjB,UAAU,EAAE,GAAG;aAChB,CAAC;QACJ,KAAK,OAAO;YACV,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,WAAW,EAAE,CAAC,OAAO,CAAC;gBACtB,YAAY,EAAE,CAAC;gBACf,UAAU,EAAE,CAAC;aACd,CAAC;QACJ,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;QACxD,KAAK,SAAS,CAAC;QACf;YACE,IAAI,cAAc,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mCAAmC,cAAc,qBAAqB,CACvE,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;IAC/D,CAAC;AACH,CAAC"}

package/payload/platform/lib/graph-search/dist/rrf-fusion.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Reciprocal Rank Fusion (Task 308).
+ *
+ * Replaces the weighted-sum fusion (`0.7 * vector + 0.3 * bm25_norm`) when
+ * the `MAXY_GS_RRF` flag is on. RRF is robust to score-distribution drift
+ * between the vector and BM25 indexes — it sums `1 / (k + rank_i)` for each
+ * node across the ranked lists it appears in. Higher rank (lower index) →
+ * larger contribution; the constant `k` (default 60, per the gbrain
+ * default) smooths the long tail.
+ *
+ * The weighted-sum baseline stays as the fallback so flag flips are
+ * reversible without code edits.
+ */
+export interface FusionCandidate {
+    nodeId: string;
+}
+/**
+ * Fuse multiple ranked lists by Reciprocal Rank Fusion.
+ *
+ * Each input list is treated as already sorted (best first). For each
+ * candidate, score = sum over lists of `1 / (k + rank)`. Returns the union
+ * sorted by descending RRF score.
+ *
+ * Ties on RRF score are broken by the candidate's earliest appearance
+ * across the input lists (first-seen wins), which is deterministic given
+ * a deterministic input order.
+ */
+export declare function fuseRrf<T extends FusionCandidate>(rankedLists: T[][], k?: number): Array<T & {
+    rrfScore: number;
+}>;
+//# sourceMappingURL=rrf-fusion.d.ts.map

package/payload/platform/lib/graph-search/dist/rrf-fusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf-fusion.d.ts","sourceRoot":"","sources":["../src/rrf-fusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,eAAe,EAC/C,WAAW,EAAE,CAAC,EAAE,EAAE,EAClB,CAAC,SAAK,GACL,KAAK,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BjC"}

package/payload/platform/lib/graph-search/dist/rrf-fusion.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Reciprocal Rank Fusion (Task 308).
+ *
+ * Replaces the weighted-sum fusion (`0.7 * vector + 0.3 * bm25_norm`) when
+ * the `MAXY_GS_RRF` flag is on. RRF is robust to score-distribution drift
+ * between the vector and BM25 indexes — it sums `1 / (k + rank_i)` for each
+ * node across the ranked lists it appears in. Higher rank (lower index) →
+ * larger contribution; the constant `k` (default 60, per the gbrain
+ * default) smooths the long tail.
+ *
+ * The weighted-sum baseline stays as the fallback so flag flips are
+ * reversible without code edits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fuseRrf = fuseRrf;
+/**
+ * Fuse multiple ranked lists by Reciprocal Rank Fusion.
+ *
+ * Each input list is treated as already sorted (best first). For each
+ * candidate, score = sum over lists of `1 / (k + rank)`. Returns the union
+ * sorted by descending RRF score.
+ *
+ * Ties on RRF score are broken by the candidate's earliest appearance
+ * across the input lists (first-seen wins), which is deterministic given
+ * a deterministic input order.
+ */
+function fuseRrf(rankedLists, k = 60) {
+    const scores = new Map();
+    const representatives = new Map();
+    const firstSeen = new Map();
+    let order = 0;
+    for (const list of rankedLists) {
+        for (let rank = 0; rank < list.length; rank++) {
+            const candidate = list[rank];
+            const contribution = 1 / (k + rank);
+            const prior = scores.get(candidate.nodeId) ?? 0;
+            scores.set(candidate.nodeId, prior + contribution);
+            if (!representatives.has(candidate.nodeId)) {
+                representatives.set(candidate.nodeId, candidate);
+                firstSeen.set(candidate.nodeId, order++);
+            }
+        }
+    }
+    const out = [];
+    for (const [nodeId, rrfScore] of scores) {
+        const rep = representatives.get(nodeId);
+        out.push({ ...rep, rrfScore });
+    }
+    out.sort((a, b) => {
+        if (b.rrfScore !== a.rrfScore)
+            return b.rrfScore - a.rrfScore;
+        return (firstSeen.get(a.nodeId) - firstSeen.get(b.nodeId));
+    });
+    return out;
+}
+//# sourceMappingURL=rrf-fusion.js.map

package/payload/platform/lib/graph-search/dist/rrf-fusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf-fusion.js","sourceRoot":"","sources":["../src/rrf-fusion.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAiBH,0BAgCC;AA3CD;;;;;;;;;;GAUG;AACH,SAAgB,OAAO,CACrB,WAAkB,EAClB,CAAC,GAAG,EAAE;IAEN,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,eAAe,GAAG,IAAI,GAAG,EAAa,CAAC;IAC7C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;YAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7B,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACpC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAChD,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,GAAG,YAAY,CAAC,CAAC;YACnD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3C,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;gBACjD,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAoC,EAAE,CAAC;IAChD,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;QACzC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IACjC,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAChB,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;YAAE,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC9D,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/payload/platform/lib/graph-search/src/__tests__/boosts.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { applyBacklinkBoost, applyCompiledTruthBoost } from "../boosts.js";
+
+describe("applyCompiledTruthBoost", () => {
+  it("is identity on hits without compiledTruth", () => {
+    const hits = [
+      { nodeId: "a", score: 1.0, properties: {} },
+      { nodeId: "b", score: 0.5, properties: { compiledTruth: null } },
+      { nodeId: "c", score: 0.3, properties: { compiledTruth: "" } },
+    ];
+    const out = applyCompiledTruthBoost(hits);
+    expect(out.map((h) => h.score)).toEqual([1.0, 0.5, 0.3]);
+  });
+
+  it("adds 15% to hits with a non-empty compiledTruth", () => {
+    const hits = [
+      { nodeId: "a", score: 1.0, properties: { compiledTruth: "Adam founded X." } },
+    ];
+    const out = applyCompiledTruthBoost(hits);
+    expect(out[0].score).toBeCloseTo(1.15, 6);
+  });
+
+  it("respects the weight override", () => {
+    const hits = [{ nodeId: "a", score: 1.0, properties: { compiledTruth: "x" } }];
+    const out = applyCompiledTruthBoost(hits, 0.25);
+    expect(out[0].score).toBeCloseTo(1.25, 6);
+  });
+
+  it("throws on out-of-range weight", () => {
+    expect(() =>
+      applyCompiledTruthBoost([{ nodeId: "a", score: 1, properties: {} }], 1.5),
+    ).toThrow();
+  });
+});
+
+describe("applyBacklinkBoost", () => {
+  it("is identity on missing or zero count", () => {
+    const hits = [
+      { nodeId: "a", score: 1.0, properties: {} },
+      { nodeId: "b", score: 1.0, properties: { backlinkCount: 0 } },
+    ];
+    const out = applyBacklinkBoost(hits);
+    expect(out.map((h) => h.score)).toEqual([1.0, 1.0]);
+  });
+
+  it("scales log-weighted with the documented floor/ceiling", () => {
+    const hits = [
+      { nodeId: "a", score: 1.0, properties: { backlinkCount: 1 } },
+      { nodeId: "b", score: 1.0, properties: { backlinkCount: 10 } },
+      { nodeId: "c", score: 1.0, properties: { backlinkCount: 100 } },
+      { nodeId: "d", score: 1.0, properties: { backlinkCount: 10_000 } },
+    ];
+    const out = applyBacklinkBoost(hits);
+    expect(out[0].score).toBeCloseTo(1.05, 6); // 1 → +5%
+    expect(out[1].score).toBeCloseTo(1.10, 6); // 10 → +10%
+    expect(out[2].score).toBeCloseTo(1.15, 6); // 100 → +15%
+    expect(out[3].score).toBeCloseTo(1.25, 6); // 10k → capped at +25%
+  });
+});

package/payload/platform/lib/graph-search/src/__tests__/dedup.test.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { DEFAULT_LAYERS, dedup } from "../dedup.js";
+
+describe("dedup", () => {
+  it("keeps the highest-score representative on nodeId collision", () => {
+    const hits = [
+      { nodeId: "a", score: 0.5, properties: {} },
+      { nodeId: "a", score: 0.9, properties: {} },
+    ];
+    const out = dedup(hits);
+    expect(out).toHaveLength(1);
+    expect(out[0].score).toBe(0.9);
+  });
+
+  it("collapses slug collisions across distinct nodeIds", () => {
+    const hits = [
+      { nodeId: "a", score: 0.9, properties: { slug: "adam-langley" } },
+      { nodeId: "b", score: 0.6, properties: { slug: "adam-langley" } },
+    ];
+    const out = dedup(hits);
+    expect(out.map((h) => h.nodeId)).toEqual(["a"]);
+  });
+
+  it("collapses canonicalName collisions case-insensitively, falls back to name", () => {
+    const hits = [
+      { nodeId: "a", score: 0.9, properties: { canonicalName: "Acme Co" } },
+      { nodeId: "b", score: 0.6, properties: { name: "acme co" } },
+    ];
+    const out = dedup(hits);
+    expect(out.map((h) => h.nodeId)).toEqual(["a"]);
+  });
+
+  it("collapses contentHash collisions (compiledTruth wins over content)", () => {
+    const hits = [
+      { nodeId: "a", score: 0.9, properties: { compiledTruth: "X" } },
+      { nodeId: "b", score: 0.6, properties: { content: "X" } },
+    ];
+    const out = dedup(hits);
+    // hash("X") matches across both → "a" wins by score.
+    expect(out.map((h) => h.nodeId)).toEqual(["a"]);
+    const h = createHash("sha256").update("X").digest("hex").slice(0, 16);
+    expect(h).toBeDefined();
+  });
+
+  it("skips a layer for hits missing its key — no false collision", () => {
+    const hits = [
+      { nodeId: "a", score: 0.9, properties: {} },
+      { nodeId: "b", score: 0.6, properties: {} },
+    ];
+    const out = dedup(hits);
+    expect(out.map((h) => h.nodeId)).toEqual(["a", "b"]);
+  });
+
+  it("honours layer subset", () => {
+    const hits = [
+      { nodeId: "a", score: 0.9, properties: { slug: "same" } },
+      { nodeId: "b", score: 0.6, properties: { slug: "same" } },
+    ];
+    // nodeId-only dedup keeps both because nodeIds differ.
+    const out = dedup(hits, ["nodeId"]);
+    expect(out).toHaveLength(2);
+  });
+
+  it("preserves descending-score order in the output", () => {
+    const hits = [
+      { nodeId: "a", score: 0.3, properties: {} },
+      { nodeId: "b", score: 0.9, properties: {} },
+      { nodeId: "c", score: 0.6, properties: {} },
+    ];
+    const out = dedup(hits);
+    expect(out.map((h) => h.score)).toEqual([0.9, 0.6, 0.3]);
+  });
+
+  it("exports the default-layers constant for reference", () => {
+    expect(DEFAULT_LAYERS).toEqual([
+      "nodeId",
+      "slug",
+      "canonicalName",
+      "contentHash",
+    ]);
+  });
+});

package/payload/platform/lib/graph-search/src/__tests__/query-expansion.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const callMock = vi.fn();
+
+vi.mock("../../../oauth-llm/dist/index.js", () => ({
+  callOauthLlm: (...args: unknown[]) => callMock(...args),
+}));
+
+import { clearExpansionCache, expandQuery } from "../query-expansion.js";
+
+describe("expandQuery", () => {
+  beforeEach(() => {
+    callMock.mockReset();
+    clearExpansionCache();
+  });
+
+  afterEach(() => {
+    callMock.mockReset();
+    clearExpansionCache();
+  });
+
+  it("returns [original, ...paraphrases] on Haiku success", async () => {
+    callMock.mockResolvedValueOnce({
+      kind: "ok-tool",
+      toolName: "emit_paraphrases",
+      input: {
+        paraphrases: ["who is adam langley", "adam langley bio", "adam langley founder"],
+      },
+    });
+    const out = await expandQuery({ query: "Adam Langley", accountId: "acc-1" });
+    expect(out[0]).toBe("Adam Langley");
+    expect(out.slice(1)).toEqual([
+      "who is adam langley",
+      "adam langley bio",
+      "adam langley founder",
+    ]);
+  });
+
+  it("serves the second identical call from cache (no second LLM call)", async () => {
+    callMock.mockResolvedValueOnce({
+      kind: "ok-tool",
+      toolName: "emit_paraphrases",
+      input: { paraphrases: ["p1", "p2", "p3"] },
+    });
+    const first = await expandQuery({ query: "X", accountId: "a" });
+    const second = await expandQuery({ query: "X", accountId: "a" });
+    expect(first).toEqual(second);
+    expect(callMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches per retrievalClass — different class re-invokes Haiku", async () => {
+    callMock.mockResolvedValueOnce({
+      kind: "ok-tool",
+      toolName: "emit_paraphrases",
+      input: { paraphrases: ["p1", "p2", "p3"] },
+    });
+    callMock.mockResolvedValueOnce({
+      kind: "ok-tool",
+      toolName: "emit_paraphrases",
+      input: { paraphrases: ["q1", "q2", "q3"] },
+    });
+    const entityCall = await expandQuery({
+      query: "X",
+      accountId: "a",
+      retrievalClass: "entity",
+    });
+    const temporalCall = await expandQuery({
+      query: "X",
+      accountId: "a",
+      retrievalClass: "temporal",
+    });
+    expect(entityCall.slice(1)).toEqual(["p1", "p2", "p3"]);
+    expect(temporalCall.slice(1)).toEqual(["q1", "q2", "q3"]);
+    expect(callMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("falls back to [query] on LLM fallback result", async () => {
+    callMock.mockResolvedValueOnce({
+      kind: "fallback",
+      cause: "missing-creds",
+      reason: "no oauth",
+    });
+    const out = await expandQuery({ query: "X", accountId: "a", useCache: false });
+    expect(out).toEqual(["X"]);
+  });
+
+  it("falls back to [query] when the tool input is malformed", async () => {
+    callMock.mockResolvedValueOnce({
+      kind: "ok-tool",
+      toolName: "emit_paraphrases",
+      input: { paraphrases: "not an array" },
+    });
+    const out = await expandQuery({ query: "X", accountId: "a", useCache: false });
+    expect(out).toEqual(["X"]);
+  });
+});

package/payload/platform/lib/graph-search/src/__tests__/route.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { pickIndexMix } from "../route.js";
+
+describe("pickIndexMix", () => {
+  it("entity → vector-heavy + Person|Company|Concept", () => {
+    const plan = pickIndexMix("entity");
+    expect(plan.skip).toBe(false);
+    expect(plan.labelFilter).toEqual(["Person", "Company", "Concept"]);
+    expect(plan.vectorWeight).toBe(0.85);
+    expect(plan.bm25Weight).toBe(0.15);
+  });
+
+  it("temporal → bm25-heavy + Event", () => {
+    const plan = pickIndexMix("temporal");
+    expect(plan.labelFilter).toEqual(["Event"]);
+    expect(plan.vectorWeight).toBe(0.2);
+    expect(plan.bm25Weight).toBe(0.8);
+  });
+
+  it("event → bm25-only + Event", () => {
+    const plan = pickIndexMix("event");
+    expect(plan.labelFilter).toEqual(["Event"]);
+    expect(plan.vectorWeight).toBe(0);
+    expect(plan.bm25Weight).toBe(1);
+  });
+
+  it("general → balanced (matches the baseline weighted-sum defaults)", () => {
+    const plan = pickIndexMix("general");
+    expect(plan.skip).toBe(false);
+    expect(plan.labelFilter).toBeUndefined();
+    expect(plan.vectorWeight).toBe(0.7);
+    expect(plan.bm25Weight).toBe(0.3);
+  });
+
+  it("none → skip", () => {
+    const plan = pickIndexMix("none");
+    expect(plan.skip).toBe(true);
+  });
+
+  it("unknown value → general (with stderr warning)", () => {
+    const errs: string[] = [];
+    const orig = process.stderr.write.bind(process.stderr);
+    (process.stderr.write as unknown as (s: string) => boolean) = (s: string) => {
+      errs.push(s);
+      return true;
+    };
+    try {
+      const plan = pickIndexMix("nonsense");
+      expect(plan.skip).toBe(false);
+      expect(plan.vectorWeight).toBe(0.7);
+    } finally {
+      (process.stderr.write as unknown as typeof orig) = orig;
+    }
+    expect(errs.some((e) => e.includes("[graph-search:unknown-class]"))).toBe(true);
+  });
+
+  it("undefined → general silently", () => {
+    const plan = pickIndexMix(undefined);
+    expect(plan.skip).toBe(false);
+    expect(plan.vectorWeight).toBe(0.7);
+  });
+});

package/payload/platform/lib/graph-search/src/__tests__/rrf-fusion.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { fuseRrf } from "../rrf-fusion.js";
+
+describe("fuseRrf", () => {
+  it("sums 1/(k+rank) per node across lists", () => {
+    const listA = [{ nodeId: "a" }, { nodeId: "b" }, { nodeId: "c" }];
+    const listB = [{ nodeId: "b" }, { nodeId: "d" }, { nodeId: "a" }];
+    const fused = fuseRrf([listA, listB], 60);
+
+    // a: list A rank 0 + list B rank 2 = 1/60 + 1/62
+    // b: list A rank 1 + list B rank 0 = 1/61 + 1/60
+    // c: list A rank 2 only           = 1/62
+    // d: list B rank 1 only           = 1/61
+    const byId = new Map(fused.map((f) => [f.nodeId, f.rrfScore]));
+    expect(byId.get("a")).toBeCloseTo(1 / 60 + 1 / 62, 6);
+    expect(byId.get("b")).toBeCloseTo(1 / 61 + 1 / 60, 6);
+    expect(byId.get("c")).toBeCloseTo(1 / 62, 6);
+    expect(byId.get("d")).toBeCloseTo(1 / 61, 6);
+  });
+
+  it("sorts by descending RRF score", () => {
+    const listA = [{ nodeId: "a" }, { nodeId: "b" }];
+    const listB = [{ nodeId: "b" }, { nodeId: "a" }];
+    const fused = fuseRrf([listA, listB], 60);
+    // Both appear in both lists at ranks (0,1) and (1,0) → same score; tie broken by first-seen → "a" first.
+    expect(fused.map((f) => f.nodeId)).toEqual(["a", "b"]);
+  });
+
+  it("honours configurable k", () => {
+    const listA = [{ nodeId: "a" }];
+    const fused = fuseRrf([listA], 10);
+    expect(fused[0].rrfScore).toBeCloseTo(1 / 10, 6);
+  });
+
+  it("returns [] for empty input", () => {
+    expect(fuseRrf([])).toEqual([]);
+    expect(fuseRrf([[], []])).toEqual([]);
+  });
+});