@rubytech/create-maxy-code 0.1.0

package/payload/platform/lib/graph-search/src/index.ts

@@ -0,0 +1,718 @@
+/**
+ * Shared hybrid search primitive over the Neo4j knowledge graph.
+ *
+ * Pre-Task-675 there were two BM25 implementations over the same fulltext
+ * index — one in the memory MCP tool, one in the admin Hono route — with
+ * divergent filter semantics (soft-delete primitive) and divergent ranking
+ * (agent ran hybrid vector+BM25, UI ran BM25-only). Task 675 collapses both
+ * into this lib; memory MCP + admin route now share a single code path so
+ * `/graph` UI ranking matches what the agent sees.
+ *
+ * Task 748 — fulltext index `knowledge_fulltext` was renamed to `entity_search`
+ * and its label union expanded from 3 labels (KnowledgeDocument | Section |
+ * Chunk) to the full operator-meaningful label set (~40 labels) on every
+ * textual property the schema's writers assign. The lib references the new
+ * name via FULLTEXT_INDEX_NAME below; the doctrine test at
+ * `__tests__/fulltext-coverage.test.ts` parses `platform/neo4j/schema.cypher`
+ * and asserts the index covers the union of `GRAPH_LABEL_COLOURS` and every
+ * label declared in the schema.
+ *
+ *   QUERY -->  EMBED -->  VECTOR SEARCH (per index) --> ┐
+ *        │                                               ├--> MERGE --> EXPAND --> RESULTS
+ *        └-->  BM25 FULL-TEXT SEARCH -------------------> ┘
+ *
+ * Hybrid merge: normalise BM25 scores to [0,1] via min-max, then combine
+ *   combined = 0.7 * vector_score + 0.3 * normalised_bm25_score
+ * Dedup by nodeId, keeping the higher combined score.
+ *
+ * Trashed nodes (`:Trashed` label + legacy `deletedAt` property) are
+ * excluded from every path via `notTrashed()` from `graph-trash`.
+ *
+ * The lib is STATELESS. Callers pass a `Session` and, for hybrid, an
+ * `embed` function. This keeps the lib independent of Ollama config and
+ * free of circular imports against each caller's own getSession/embed
+ * (memory MCP and the Hono ui build each have their own copies for
+ * cross-build-boundary reasons — see neo4j-store.ts:68 comment).
+ *
+ * Log emission is the caller's responsibility — the lib throws or returns
+ * `mode` in the result so the caller can format its own `[graph-search]`
+ * line with the prefix and fields it wants.
+ */
+
+import { int, type Session } from "neo4j-driver";
+import { notTrashed } from "../../graph-trash/dist/index.js";
+
+const VECTOR_WEIGHT = 0.7;
+const BM25_WEIGHT = 0.3;
+/**
+ * Name of the universal fulltext index (Task 748). Mirrors the `CREATE FULLTEXT
+ * INDEX` declaration in `platform/neo4j/schema.cypher`. The doctrine test
+ * (`__tests__/fulltext-coverage.test.ts`) asserts the schema's index name
+ * matches this constant — drift between the two breaks BM25 silently.
+ */
+export const FULLTEXT_INDEX_NAME = "entity_search";
+
+export interface SearchHit {
+  nodeId: string;
+  labels: string[];
+  properties: Record<string, unknown>;
+  score: number;
+}
+
+export interface SearchResult extends SearchHit {
+  /**
+   * Task 878 — granular component scores so the /data UI can render
+   * `vector N.NN · bm25 N.NN · combined N.NN` per row. `vectorScore` is the
+   * raw cosine in [0,1] from the per-label vector index; `bm25Score` is the
+   * post-merge normalised value in [0,1] used in the combine (NOT the raw
+   * Lucene score, which has no operator-meaningful unit). Either may be 0
+   * when only one half of the hybrid hit. In the degraded (bm25-only) path
+   * `vectorScore` is always 0 and `bm25Score` is normalised over the
+   * local hit set.
+   */
+  vectorScore: number;
+  bm25Score: number;
+  related: Array<{
+    /**
+     * Task 747 — neighbour `elementId`. Required by the /graph canvas to
+     * render edges in pipeline-collapse mode (search response IS the canvas
+     * data). The MCP memory-search tool ignores it; the field is additive.
+     */
+    nodeId: string;
+    relationship: string;
+    direction: string;
+    labels: string[];
+    properties: Record<string, unknown>;
+  }>;
+}
+
+export interface ScoredNode {
+  nodeId: string;
+  labels: string[];
+  properties: Record<string, unknown>;
+  vectorScore: number;
+  bm25Score: number;
+  /**
+   * Task 967 — true when this node entered the merge map via the BM25 path
+   * with a raw Lucene score > 0 (literal-token match against the universal
+   * fulltext index), or via the keyword-subscriptions property-lookup path.
+   * Set BEFORE bm25 normalisation, so a single-hit set whose normalised
+   * value collapses to 0.0 still carries the flag.
+   *
+   * Read by the vector-threshold filter as the carve-out predicate: rows
+   * with weak cosine survive when `bm25Hit` is true (operator's literal
+   * tokens override the semantic similarity floor). Without this flag the
+   * naive `bm25Score > 0` check would drop every bottom-of-set BM25 row
+   * because min-max normalisation pins the lowest score to 0.
+   */
+  bm25Hit: boolean;
+}
+
+export type SearchMode = "hybrid" | "bm25";
+
+export interface Bm25OnlyParams {
+  query: string;
+  accountId?: string;
+  limit: number;
+  allowedScopes?: string[];
+  agentSlug?: string;
+  keywords?: string[];
+  keywordMatch?: "any" | "all";
+  /**
+   * Task 747 — gate BM25 hits to nodes carrying at least one of these labels.
+   * Mirrors hybrid()'s vector-half label filter so the Ollama-down fallback
+   * honours the same gate the operator applied via /graph chips. Empty array
+   * is treated as "no gate" (matches hybrid's `labels && labels.length > 0`
+   * guard); admin route enforces non-empty `labels` as a precondition.
+   */
+  labels?: string[];
+}
+
+export interface HybridParams extends Bm25OnlyParams {
+  expandHops?: number;
+  keywordSubscriptions?: string[];
+  /**
+   * When true, a failing `embed()` does NOT throw — the lib falls back to
+   * `bm25Only()` and returns `mode: "bm25"`. Admin-route callers set this
+   * true so Ollama-down degrades to BM25-only; MCP tool callers leave it
+   * false so embed failure surfaces loudly.
+   */
+  degradeOnEmbedFailure?: boolean;
+  /**
+   * Task 967 — minimum raw vector cosine in [0,1] required for a row to
+   * pass the merge step. Rows below the threshold are dropped UNLESS they
+   * also entered via the BM25 path (`bm25Hit === true`) — that carve-out
+   * preserves literal-token matches whose embedding happened to score
+   * mediocre. Counts surface in HybridResponse so callers can render an
+   * "N suppressed — show all" affordance.
+   *
+   * Undefined ⇒ no threshold (legacy behaviour; memory MCP keeps this).
+   * Zero ⇒ explicit "show all" override (admin route's /data and /graph
+   * surfaces use this when the operator clicks "show all").
+   *
+   * Calibration: see `DEFAULT_VECTOR_THRESHOLD` in
+   * `platform/ui/server/routes/admin/graph-search.ts` for the route's
+   * default; the lib itself takes no opinion on the value.
+   */
+  vectorThreshold?: number;
+}
+
+export interface HybridResponse {
+  mode: SearchMode;
+  results: SearchResult[];
+  /** Populated when degradeOnEmbedFailure fired. Caller logs it. */
+  embedError?: string;
+  /**
+   * Task 747 — milliseconds spent on the batched expand round-trip alone
+   * (separate from embed + vector + BM25). The /graph admin route emits
+   * this as `expand-ms=N` so a regression on the post-Task-747 batching
+   * surfaces in server.log without needing a profiler. Zero when
+   * `expandHops === 0` or no merged results.
+   */
+  expandMs: number;
+  /**
+   * Task 967 — operator-facing threshold accounting.
+   *
+   * `rawMerged`     count of nodes in the merge map BEFORE the threshold
+   *                 filter ran (vector + BM25 + keyword-subscriptions
+   *                 union, deduped by nodeId).
+   * `suppressed`    count of nodes the threshold filter dropped.
+   *                 Always 0 when `vectorThreshold` is undefined.
+   * `bm25Bypass`    count of nodes that would have been dropped by the
+   *                 vector-cosine floor BUT survived because `bm25Hit`
+   *                 was true. Subset of the rendered set.
+   * `threshold`     the actual threshold applied (echoes the param);
+   *                 null when no filter ran. Drives the "show all"
+   *                 affordance: if null, no banner; if non-null and
+   *                 `suppressed > 0`, banner with count.
+   */
+  rawMerged: number;
+  suppressed: number;
+  bm25Bypass: number;
+  threshold: number | null;
+}
+
+export type EmbedFn = (text: string) => Promise<number[]>;
+
+/**
+ * Lucene-escape special characters per Neo4j's fulltext query grammar.
+ * `/[+\-&|!(){}[\]^"~*?:\\/]/g` — matches memory-search.ts:127 and
+ * neo4j-store.ts:2521 verbatim; consolidation preserves escape set.
+ */
+export function escapeLucene(query: string): string {
+  return query.replace(/[+\-&|!(){}[\]^"~*?:\\/]/g, "\\$&");
+}
+
+/**
+ * Normalise BM25 scores to [0, 1] using min-max within the result set.
+ * If all scores are equal (or single result), returns 1.0 for all —
+ * the range-zero branch prevents divide-by-zero and keeps the combined
+ * score meaningful.
+ */
+export function normaliseBm25Scores(scores: number[]): number[] {
+  if (scores.length === 0) return [];
+  const min = Math.min(...scores);
+  const max = Math.max(...scores);
+  const range = max - min;
+  if (range === 0) return scores.map(() => 1.0);
+  return scores.map((s) => (s - min) / range);
+}
+
+// Module-scope vector-index cache — discovered from Neo4j at first query.
+// Per-process singleton matches memory-search.ts behaviour.
+let indexCache: Map<string, string> | null = null;
+
+export async function discoverIndexes(session: Session): Promise<Map<string, string>> {
+  if (indexCache) return indexCache;
+  const result = await session.run(
+    `SHOW INDEXES YIELD name, labelsOrTypes, type WHERE type = 'VECTOR' RETURN name, labelsOrTypes`
+  );
+  const fresh = new Map<string, string>();
+  for (const record of result.records) {
+    const name = record.get("name") as string;
+    const labels = record.get("labelsOrTypes") as string[];
+    for (const label of labels) fresh.set(label, name);
+  }
+  indexCache = fresh;
+  return fresh;
+}
+
+/** Clear the index cache — call after schema changes. */
+export function clearIndexCache(): void {
+  indexCache = null;
+}
+
+interface KeywordFilter {
+  clause: string;
+  params: Record<string, unknown>;
+}
+
+function buildKeywordFilter(
+  keywords: string[] | undefined,
+  keywordMatch: "any" | "all" = "any",
+): KeywordFilter | undefined {
+  if (!keywords || keywords.length === 0) return undefined;
+  const fn = keywordMatch === "all" ? "ALL" : "ANY";
+  return {
+    clause: `AND (node.keywords IS NULL OR ${fn}(kw IN $keywords WHERE kw IN node.keywords))`,
+    params: { keywords: keywords.map((k) => k.toLowerCase().trim()) },
+  };
+}
+
+/**
+ * BM25 full-text search against the universal `entity_search` index (Task 748).
+ * Returns [] when the index doesn't exist — matches memory-search.ts
+ * graceful-fallback semantics so a fresh account or a Pi mid-migration
+ * (POPULATING window) doesn't 500 the caller.
+ */
+export async function bm25Only(
+  session: Session,
+  params: Bm25OnlyParams,
+): Promise<SearchHit[]> {
+  const { query, accountId, limit, allowedScopes, agentSlug, keywords, keywordMatch, labels } = params;
+  const scopeClause = allowedScopes
+    ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
+    : "";
+  const agentClause = agentSlug
+    ? "AND node.agents IS NOT NULL AND $agentSlug IN node.agents"
+    : "";
+  const labelClause = labels && labels.length > 0
+    ? "AND any(l IN labels(node) WHERE l IN $labels)"
+    : "";
+  const keywordFilter = buildKeywordFilter(keywords, keywordMatch);
+  const kwClause = keywordFilter?.clause ?? "";
+  const escaped = escapeLucene(query);
+
+  try {
+    const result = await session.run(
+      `CALL db.index.fulltext.queryNodes($indexName, $query)
+       YIELD node, score
+       WHERE node.accountId = $accountId
+       ${scopeClause}
+       ${agentClause}
+       ${labelClause}
+       AND ${notTrashed("node")}
+       ${kwClause}
+       RETURN node, score, labels(node) AS nodeLabels, elementId(node) AS nodeId
+       ORDER BY score DESC
+       LIMIT $limit`,
+      {
+        indexName: FULLTEXT_INDEX_NAME,
+        query: escaped,
+        accountId,
+        limit: int(limit),
+        ...(allowedScopes ? { allowedScopes } : {}),
+        ...(agentSlug ? { agentSlug } : {}),
+        ...(labels && labels.length > 0 ? { labels } : {}),
+        ...(keywordFilter?.params ?? {}),
+      },
+    );
+    return result.records.map((r) => {
+      const scoreRaw = r.get("score");
+      const score = typeof scoreRaw === "number" ? scoreRaw : Number(scoreRaw);
+      const node = r.get("node") as { properties: Record<string, unknown> };
+      return {
+        nodeId: r.get("nodeId") as string,
+        labels: r.get("nodeLabels") as string[],
+        properties: plainProperties(node.properties),
+        score,
+      };
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("index") || msg.includes("fulltext") || msg.includes("not found")) {
+      return [];
+    }
+    throw err;
+  }
+}
+
+/**
+ * Hybrid vector + BM25 search with graph expansion.
+ *
+ * Sequence:
+ *  1. embed(query) — may throw if Ollama is unreachable. When
+ *     `degradeOnEmbedFailure=true`, caller receives bm25Only() result
+ *     with `mode: "bm25"`; otherwise the throw propagates.
+ *  2. Vector search per label (one query per vector index discovered at
+ *     boot). Nodes-by-label filter short-circuits when the requested
+ *     labels have no index.
+ *  3. BM25 search on the universal `entity_search` index (Task 748) —
+ *     same filter semantics as vector half (scope/agent/keyword/trashed).
+ *  4. Keyword subscriptions (when set): BM25 per keyword + property
+ *     lookup against `node.keywords` array. Both bypass the agentSlug
+ *     filter — subscriptions are scope-inclusive by design (matches
+ *     memory-search.ts comment L319).
+ *  5. Merge: 0.7*vector + 0.3*bm25_norm, dedup by nodeId, sort.
+ *  6. Graph expand (1 hop by default, 0 to skip) — notTrashed filter +
+ *     scope + agent clauses mirrored.
+ */
+export async function hybrid(
+  session: Session,
+  embed: EmbedFn,
+  params: HybridParams,
+): Promise<HybridResponse> {
+  const {
+    query,
+    labels,
+    accountId,
+    limit,
+    allowedScopes,
+    keywords,
+    keywordMatch = "any",
+    agentSlug,
+    keywordSubscriptions,
+    expandHops = 1,
+    degradeOnEmbedFailure = false,
+  } = params;
+
+  let queryEmbedding: number[];
+  try {
+    queryEmbedding = await embed(query);
+  } catch (err) {
+    if (!degradeOnEmbedFailure) throw err;
+    const msg = err instanceof Error ? err.message : String(err);
+    const bm25Hits = await bm25Only(session, params);
+    // Task 878 — even in the degraded path, surface granular components so
+    // the /data score-line renders consistently. Vector half is 0 (no embed
+    // happened); bm25 half is normalised across the local hit set.
+    const normalised = normaliseBm25Scores(bm25Hits.map((h) => h.score));
+    const results: SearchResult[] = bm25Hits.map((h, i) => ({
+      ...h,
+      vectorScore: 0,
+      bm25Score: normalised[i] ?? 0,
+      related: [],
+    }));
+    // Task 967 — threshold has no meaning in the degraded path: no embed
+    // happened, so there is no vector cosine to compare against. Surface
+    // counts in the response (rawMerged = rendered, suppressed = 0,
+    // bm25Bypass = 0, threshold = null) so the caller's render path is
+    // uniform across hybrid + degraded modes.
+    return {
+      mode: "bm25",
+      results,
+      embedError: msg,
+      expandMs: 0,
+      rawMerged: results.length,
+      suppressed: 0,
+      bm25Bypass: 0,
+      threshold: null,
+    };
+  }
+
+  const labelToIndex = await discoverIndexes(session);
+
+  const keywordFilter = buildKeywordFilter(keywords, keywordMatch);
+  const keywordClause = keywordFilter?.clause ?? "";
+  const keywordParams = keywordFilter?.params ?? {};
+
+  const scoreMap = new Map<string, ScoredNode>();
+
+  // --- Vector search (per label) ---
+  let indexesToQuery: string[];
+  if (labels && labels.length > 0) {
+    indexesToQuery = labels
+      .map((l) => labelToIndex.get(l))
+      .filter((idx): idx is string => idx !== undefined);
+    if (indexesToQuery.length === 0) {
+      return {
+        mode: "hybrid",
+        results: [],
+        expandMs: 0,
+        rawMerged: 0,
+        suppressed: 0,
+        bm25Bypass: 0,
+        threshold: params.vectorThreshold ?? null,
+      };
+    }
+  } else {
+    indexesToQuery = [...new Set(labelToIndex.values())];
+  }
+
+  const scopeClause = allowedScopes
+    ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
+    : "";
+  const scopeParams = allowedScopes ? { allowedScopes } : {};
+  const agentClause = agentSlug
+    ? "AND node.agents IS NOT NULL AND $agentSlug IN node.agents"
+    : "";
+  const agentParams = agentSlug ? { agentSlug } : {};
+
+  for (const indexName of indexesToQuery) {
+    const vectorResult = await session.run(
+      `CALL db.index.vector.queryNodes($indexName, $limit, $embedding)
+       YIELD node, score
+       WHERE node.accountId = $accountId
+       ${scopeClause}
+       ${agentClause}
+       AND ${notTrashed("node")}
+       ${keywordClause}
+       RETURN node, score, labels(node) AS nodeLabels, elementId(node) AS nodeId
+       ORDER BY score DESC
+       LIMIT $limit`,
+      {
+        indexName,
+        embedding: queryEmbedding,
+        limit: int(limit),
+        accountId,
+        ...scopeParams,
+        ...agentParams,
+        ...keywordParams,
+      },
+    );
+    for (const record of vectorResult.records) {
+      const nodeId = record.get("nodeId") as string;
+      const scoreRaw = record.get("score");
+      const score = typeof scoreRaw === "number" ? scoreRaw : Number(scoreRaw);
+      const existing = scoreMap.get(nodeId);
+      if (existing) {
+        existing.vectorScore = Math.max(existing.vectorScore, score);
+      } else {
+        const node = record.get("node") as { properties: Record<string, unknown> };
+        scoreMap.set(nodeId, {
+          nodeId,
+          labels: record.get("nodeLabels") as string[],
+          properties: plainProperties(node.properties),
+          vectorScore: score,
+          bm25Score: 0,
+          bm25Hit: false,
+        });
+      }
+    }
+  }
+
+  // --- BM25 half ---
+  const bm25Hits = await bm25Only(session, params);
+  if (bm25Hits.length > 0) {
+    const rawScores = bm25Hits.map((h) => h.score);
+    const normalised = normaliseBm25Scores(rawScores);
+    for (let i = 0; i < bm25Hits.length; i++) {
+      mergeBm25Hit(scoreMap, bm25Hits[i], normalised[i]);
+    }
+  }
+
+  // --- Keyword subscriptions (scope-inclusive, agentSlug-bypassing) ---
+  if (keywordSubscriptions && keywordSubscriptions.length > 0) {
+    for (const kw of keywordSubscriptions) {
+      const kwHits = await bm25Only(session, {
+        query: kw,
+        accountId,
+        limit,
+        allowedScopes,
+      });
+      if (kwHits.length === 0) continue;
+      const rawScores = kwHits.map((h) => h.score);
+      const normalised = normaliseBm25Scores(rawScores);
+      for (let i = 0; i < kwHits.length; i++) {
+        mergeBm25Hit(scoreMap, kwHits[i], normalised[i]);
+      }
+    }
+
+    const propScopeClause = allowedScopes
+      ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
+      : "";
+    const propResult = await session.run(
+      `MATCH (node)
+       WHERE node.accountId = $accountId
+       AND ${notTrashed("node")}
+       AND node.keywords IS NOT NULL
+       AND ANY(kw IN $kwSubs WHERE ANY(nk IN node.keywords WHERE toLower(nk) = kw))
+       ${propScopeClause}
+       RETURN node, labels(node) AS nodeLabels, elementId(node) AS nodeId
+       LIMIT $limit`,
+      {
+        accountId,
+        kwSubs: keywordSubscriptions,
+        limit: int(limit),
+        ...(allowedScopes ? { allowedScopes } : {}),
+      },
+    );
+    for (const record of propResult.records) {
+      const nodeId = record.get("nodeId") as string;
+      const existing = scoreMap.get(nodeId);
+      if (existing) {
+        existing.bm25Score = Math.max(existing.bm25Score, 1.0);
+        existing.bm25Hit = true;
+      } else {
+        const node = record.get("node") as { properties: Record<string, unknown> };
+        scoreMap.set(nodeId, {
+          nodeId,
+          labels: record.get("nodeLabels") as string[],
+          properties: plainProperties(node.properties),
+          vectorScore: 0,
+          bm25Score: 1.0,
+          bm25Hit: true,
+        });
+      }
+    }
+  }
+
+  // --- Merge, threshold, rank ---
+  //
+  // Task 967 — vectorThreshold filters BEFORE sort+slice. Order matters:
+  // slicing first would consume the slot budget with rows the threshold
+  // would have suppressed, under-filling the rendered set. Sorting before
+  // filtering would waste cycles ordering rows we are about to drop. So:
+  // filter -> sort -> slice. Counts (rawMerged / suppressed / bm25Bypass)
+  // are computed against the pre-filter and post-filter populations so the
+  // route can render "N suppressed — show all" without a second query.
+  //
+  // Carve-out: a row with vector cosine below the threshold survives iff
+  // bm25Hit is true. The flag (not bm25Score) is the gate — min-max
+  // normalisation pins the lowest BM25 row's score to 0.0, so checking
+  // bm25Score > 0 would silently drop a literal-token match that just
+  // happens to be the worst-scored BM25 hit in the set.
+  const allMerged = [...scoreMap.values()].map((node) => ({
+    ...node,
+    combinedScore: VECTOR_WEIGHT * node.vectorScore + BM25_WEIGHT * node.bm25Score,
+  }));
+  const rawMerged = allMerged.length;
+  const threshold = params.vectorThreshold;
+  let kept = allMerged;
+  let bm25Bypass = 0;
+  if (threshold !== undefined) {
+    kept = [];
+    for (const node of allMerged) {
+      if (node.vectorScore >= threshold) {
+        kept.push(node);
+      } else if (node.bm25Hit) {
+        kept.push(node);
+        bm25Bypass++;
+      }
+    }
+  }
+  const suppressed = rawMerged - kept.length;
+  const merged = kept
+    .sort((a, b) => b.combinedScore - a.combinedScore)
+    .slice(0, limit);
+
+  // --- Graph expand (Task 747 — single batched round-trip) ---
+  //
+  // Pre-Task-747: one Cypher per merged node, in a JS for-loop. At the admin
+  // route's slider=2000 this produced 2000 driver round-trips per search.
+  //
+  // Post-Task-747: one UNWIND-driven query for all merged nodeIds. The
+  // `WITH nid, collect({...})[0..20]` clause preserves the per-result cap of
+  // 20 neighbours that the per-node query enforced via `LIMIT 20`. Slice
+  // notation is order-preserving over the rows it consumes (no upstream
+  // ORDER BY changes that), so canvas-edge density per hit is unchanged.
+  //
+  // Each `related` entry now carries `relatedNodeId` (the neighbour's
+  // elementId) so the /graph canvas can render edges in pipeline-collapse
+  // mode (search response IS the canvas data when `q` is set).
+  const results: SearchResult[] = merged.map((node) => ({
+    nodeId: node.nodeId,
+    labels: node.labels,
+    properties: node.properties,
+    score: node.combinedScore,
+    // Task 878 — carry the per-half components so the /data UI can render
+    // a per-row breakdown. These are already computed on `ScoredNode` from
+    // the vector half (raw cosine) and the bm25 half (post-merge normalised
+    // value, NOT raw Lucene). Memory MCP ignores both; admin route forwards
+    // them through SearchResult to the wire.
+    vectorScore: node.vectorScore,
+    bm25Score: node.bm25Score,
+    related: [],
+  }));
+
+  let expandMs = 0;
+  if (expandHops > 0 && results.length > 0) {
+    const expandScopeClause = allowedScopes
+      ? "AND (related.scope IS NULL OR related.scope IN $allowedScopes)"
+      : "";
+    const expandAgentClause = agentSlug
+      ? "AND (related.agents IS NULL OR $agentSlug IN related.agents)"
+      : "";
+    const expandStart = Date.now();
+    const expandResult = await session.run(
+      `UNWIND $nodeIds AS nid
+       MATCH (n)-[r]-(related)
+       WHERE elementId(n) = nid
+       AND ${notTrashed("related")}
+       ${expandScopeClause}
+       ${expandAgentClause}
+       WITH nid, n, r, related
+       WITH nid, collect({
+         relType: type(r),
+         direction: CASE WHEN startNode(r) = n THEN 'outgoing' ELSE 'incoming' END,
+         relatedNodeId: elementId(related),
+         relatedLabels: labels(related),
+         related: related
+       })[0..20] AS items
+       RETURN nid, items`,
+      { nodeIds: results.map((r) => r.nodeId), ...scopeParams, ...agentParams },
+    );
+    expandMs = Date.now() - expandStart;
+    const byNodeId = new Map<string, SearchResult>(results.map((r) => [r.nodeId, r]));
+    for (const rec of expandResult.records) {
+      const nid = rec.get("nid") as string;
+      const target = byNodeId.get(nid);
+      if (!target) continue;
+      const items = rec.get("items") as Array<{
+        relType: string;
+        direction: string;
+        relatedNodeId: string;
+        relatedLabels: string[];
+        related: { properties: Record<string, unknown> };
+      }>;
+      for (const item of items) {
+        target.related.push({
+          nodeId: item.relatedNodeId,
+          relationship: item.relType,
+          direction: item.direction,
+          labels: item.relatedLabels,
+          properties: plainProperties(item.related.properties),
+        });
+      }
+    }
+  }
+
+  return {
+    mode: "hybrid",
+    results,
+    expandMs,
+    rawMerged,
+    suppressed,
+    bm25Bypass,
+    threshold: threshold ?? null,
+  };
+}
+
+function mergeBm25Hit(
+  map: Map<string, ScoredNode>,
+  hit: SearchHit,
+  normalisedScore: number,
+): void {
+  const existing = map.get(hit.nodeId);
+  if (existing) {
+    existing.bm25Score = Math.max(existing.bm25Score, normalisedScore);
+    // Task 967 — set bm25Hit irrespective of normalised value. The hit
+    // came from db.index.fulltext.queryNodes (raw Lucene score > 0 by
+    // construction); min-max normalisation pinning the lowest row to
+    // 0.0 is a presentation artefact, not a "no match" signal.
+    existing.bm25Hit = true;
+  } else {
+    map.set(hit.nodeId, {
+      nodeId: hit.nodeId,
+      labels: hit.labels,
+      properties: hit.properties,
+      vectorScore: 0,
+      bm25Score: normalisedScore,
+      bm25Hit: true,
+    });
+  }
+}
+
+/** Strip `embedding` and unwrap Neo4j Integers into JS numbers. */
+function plainProperties(properties: Record<string, unknown>): Record<string, unknown> {
+  const plain: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (key === "embedding") continue;
+    if (value && typeof value === "object" && "toNumber" in value) {
+      plain[key] = (value as { toNumber(): number }).toNumber();
+    } else {
+      plain[key] = value;
+    }
+  }
+  return plain;
+}