@klhapp/skillmux 1.0.1 → 1.2.0

package/src/config.ts

@@ -48,14 +48,14 @@ const configSchema = z.object({
       timeout_ms: z.number().int().min(100),
       embedding: z.object({
         provider: z.literal("openai"),
-        base_url: z.url(),
+        endpoint: z.url(),
         model: z.string().min(1),
         dimension: z.number().int().positive(),
         api_key_env: z.string().min(1).optional(),
       }).strict(),
       reranker: z.object({
-        provider: z.literal("infinity"),
-        base_url: z.url(),
+        adapter: z.enum(["jina-v1", "bifrost-v1"]),
+        endpoint: z.url(),
         model: z.string().min(1),
         api_key_env: z.string().min(1).optional(),
       }).strict().optional(),
@@ -133,6 +133,12 @@ export function embeddingFingerprint(config: Config): string {
   return `${implementation}:${inference.embedding.model}:${inference.embedding.dimension}`;
 }
 
+export function rerankerFingerprint(config: Config): string | undefined {
+  const inference = config.inference;
+  if (inference.mode !== "remote" || !inference.reranker) return undefined;
+  return `remote:${inference.reranker.adapter}:${inference.reranker.model}`;
+}
+
 export function expandHome(path: string): string {
   return path.startsWith("~") ? join(homedir(), path.slice(1)) : path;
 }
@@ -183,6 +189,30 @@ export function resolveConfigPath(path?: string): string {
 
 export async function loadConfig(path?: string): Promise<Config> {
   migrateLegacyPaths();
+  const removedRerankerEnv = [
+    "SKILLMUX_RERANK_BASE_URL",
+    "SKILL_ROUTER_RERANK_BASE_URL",
+    "RERANK_BASE_URL",
+  ].find((name) => process.env[name] !== undefined);
+  if (removedRerankerEnv) {
+    throw new Error(
+      `${removedRerankerEnv} is no longer supported. Configure ` +
+        "inference.reranker.endpoint with the complete request URL and " +
+        'inference.reranker.adapter (for example, "jina-v1"). The old client appended /rerank.',
+    );
+  }
+  const removedEmbeddingEnv = [
+    "SKILLMUX_EMBED_BASE_URL",
+    "SKILL_ROUTER_EMBED_BASE_URL",
+    "EMBED_BASE_URL",
+  ].find((name) => process.env[name] !== undefined);
+  if (removedEmbeddingEnv) {
+    throw new Error(
+      `${removedEmbeddingEnv} is no longer supported. Configure ` +
+        "inference.embedding.endpoint with the complete OpenAI-compatible embeddings request URL. " +
+        "The old client appended /v1/embeddings.",
+    );
+  }
   const configPath = resolveConfigPath(path);
   const file = Bun.file(expandHome(configPath));
 
@@ -204,6 +234,27 @@ export async function loadConfig(path?: string): Promise<Config> {
         "Legacy inference config is not supported. Move [embedding], [rerank], and remote_timeout_ms under [inference] using config.remote.example.toml.",
       );
     }
+    const rawReranker = isPlainObject(parsed.inference)
+      ? parsed.inference.reranker
+      : undefined;
+    const rawEmbedding = isPlainObject(parsed.inference)
+      ? parsed.inference.embedding
+      : undefined;
+    if (
+      isPlainObject(rawReranker) &&
+      ("provider" in rawReranker || "base_url" in rawReranker)
+    ) {
+      throw new Error(
+        "inference.reranker.provider and inference.reranker.base_url are no longer supported. " +
+          "Use adapter and the complete endpoint URL instead; the old client appended /rerank.",
+      );
+    }
+    if (isPlainObject(rawEmbedding) && "base_url" in rawEmbedding) {
+      throw new Error(
+        "inference.embedding.base_url is no longer supported. Use inference.embedding.endpoint " +
+          "with the complete OpenAI-compatible embeddings request URL; the old client appended /v1/embeddings.",
+      );
+    }
     if (isPlainObject(parsed.inference) && parsed.inference.mode === "remote") {
       if (!isPlainObject(parsed.inference.embedding)) {
         throw new Error("Remote inference requires an inference.embedding section.");
@@ -258,46 +309,76 @@ export async function loadConfig(path?: string): Promise<Config> {
     if (merged.inference.embedding?.provider !== "openai") {
       throw new Error('Remote inference.embedding.provider must be "openai".');
     }
-    if (merged.inference.reranker && merged.inference.reranker.provider !== "infinity") {
-      throw new Error('Remote inference.reranker.provider must be "infinity".');
-    }
     if (!Number.isInteger(merged.inference.timeout_ms) || merged.inference.timeout_ms < 100) {
       throw new Error("Remote inference.timeout_ms must be an integer of at least 100.");
     }
-    if (!merged.inference.embedding?.base_url || !merged.inference.embedding.model || !merged.inference.embedding.dimension) {
-      throw new Error("Remote inference requires inference.embedding base_url, model, and dimension.");
+    if (!merged.inference.embedding?.endpoint || !merged.inference.embedding.model || !merged.inference.embedding.dimension) {
+      throw new Error("Remote inference requires inference.embedding endpoint, model, and dimension.");
     }
-    if (merged.inference.reranker && (!merged.inference.reranker.base_url || !merged.inference.reranker.model)) {
-      throw new Error("Configured inference.reranker requires base_url and model.");
+    if (merged.inference.reranker && (!merged.inference.reranker.endpoint || !merged.inference.reranker.model)) {
+      throw new Error("Configured inference.reranker requires adapter, endpoint, and model.");
     }
     if (merged.inference.reranker && !merged.inference.thresholds) {
-      throw new Error("Configured inference.reranker requires calibrated inference.thresholds.");
-    }
-    for (const [name, value] of [
-      ["inference.embedding.base_url", merged.inference.embedding.base_url],
-      ...(merged.inference.reranker ? [["inference.reranker.base_url", merged.inference.reranker.base_url] as const] : []),
-    ] as const) {
-      try {
-        const url = new URL(value);
-        if (!['http:', 'https:'].includes(url.protocol)) throw new Error();
-      } catch {
-        throw new Error(`${name} must be an HTTP(S) URL.`);
+      const warningKey = "inference.reranker.without-thresholds";
+      if (!warnedEnv.has(warningKey)) {
+        warnedEnv.add(warningKey);
+        console.error(
+          "skillmux: configured reranker has no calibrated inference.thresholds; " +
+            "routing will remain ambiguous until you run `skillmux calibrate run`.",
+        );
       }
     }
-    const embedUrl = getEnv("SKILLMUX_EMBED_BASE_URL", "EMBED_BASE_URL");
+    const embedEndpoint = getEnv("SKILLMUX_EMBED_ENDPOINT", "EMBED_ENDPOINT");
     const embedModel = getEnv("SKILLMUX_EMBED_MODEL", "EMBED_MODEL");
     const embedDimStr = getEnv("SKILLMUX_EMBED_DIMENSION", "EMBED_DIMENSION");
-    const rerankUrl = getEnv("SKILLMUX_RERANK_BASE_URL", "RERANK_BASE_URL");
+    const rerankEndpoint = getEnv("SKILLMUX_RERANK_ENDPOINT", "RERANK_ENDPOINT");
+    const rerankAdapter = getEnv("SKILLMUX_RERANK_ADAPTER", "RERANK_ADAPTER");
     const rerankModel = getEnv("SKILLMUX_RERANK_MODEL", "RERANK_MODEL");
-    if (embedUrl) merged.inference.embedding.base_url = embedUrl;
+    if (embedEndpoint) merged.inference.embedding.endpoint = embedEndpoint;
     if (embedModel) merged.inference.embedding.model = embedModel;
-    if (rerankUrl && merged.inference.reranker) merged.inference.reranker.base_url = rerankUrl;
+    if (rerankEndpoint && merged.inference.reranker) merged.inference.reranker.endpoint = rerankEndpoint;
+    if (rerankAdapter && merged.inference.reranker) {
+      merged.inference.reranker.adapter = rerankAdapter as "jina-v1" | "bifrost-v1";
+    }
     if (rerankModel && merged.inference.reranker) merged.inference.reranker.model = rerankModel;
     if (embedDimStr) {
       const dimension = Number(embedDimStr);
       if (!Number.isInteger(dimension) || dimension < 1) throw new Error(`Invalid embedding dimension: ${embedDimStr}`);
       merged.inference.embedding.dimension = dimension;
     }
+    for (const [name, value, exactEndpoint] of [
+      ["inference.embedding.endpoint", merged.inference.embedding.endpoint, true],
+      ...(merged.inference.reranker
+        ? [["inference.reranker.endpoint", merged.inference.reranker.endpoint, true] as const]
+        : []),
+    ] as const) {
+      try {
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol)) throw new Error();
+        if (exactEndpoint && (url.username || url.password || url.hash)) throw new Error();
+      } catch {
+        throw new Error(
+          exactEndpoint
+            ? `${name} must be an absolute HTTP(S) URL without userinfo or a fragment.`
+            : `${name} must be an HTTP(S) URL.`,
+        );
+      }
+    }
+    for (const [name, apiKeyEnv] of [
+      ["inference.embedding.api_key_env", merged.inference.embedding.api_key_env],
+      ...(merged.inference.reranker
+        ? [["inference.reranker.api_key_env", merged.inference.reranker.api_key_env] as const]
+        : []),
+    ] as const) {
+      if (
+        apiKeyEnv !== undefined &&
+        (process.env[apiKeyEnv] === undefined || process.env[apiKeyEnv] === "")
+      ) {
+        throw new Error(
+          `${name} names environment variable "${apiKeyEnv}", but it is unset or empty.`,
+        );
+      }
+    }
   } else {
     throw new Error(`Invalid inference.mode: ${(merged.inference as { mode?: unknown }).mode}`);
   }

package/src/dataset-generator.ts

@@ -13,14 +13,45 @@ export interface GenerateDatasetOptions {
   queriesPerSplit?: number;
 }
 
-const GENERIC_NO_MATCH_QUERIES = [
-  "what is the weather in Paris today",
-  "recipe for baking sourdough bread at home",
-  "what is the distance from Earth to Mars",
-  "explain quantum entanglement simply",
-  "how do I solve a quadratic equation",
-  "who won the 1998 World Cup",
-];
+const STOP_WORDS = new Set([
+  "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "in", "is",
+  "it", "of", "on", "or", "the", "this", "to", "use", "with",
+]);
+
+function words(value: string): string[] {
+  return value
+    .toLowerCase()
+    .match(/[a-z0-9]+/g)
+    ?.filter((word) => word.length > 2 && !STOP_WORDS.has(word)) ?? [];
+}
+
+function anchors(skill: VaultSkill): string[] {
+  const preferred = [...skill.aliases.flatMap(words), ...words(skill.title)];
+  const fallback = words(skill.description);
+  return [...new Set([...preferred, ...fallback])].slice(0, 2);
+}
+
+function matchedQuery(skill: VaultSkill, variant: number): string {
+  const [first = "specialized", second = "workflow"] = anchors(skill);
+  const templates = [
+    `I need practical guidance completing an unfamiliar ${first} ${second} task safely`,
+    `Which available workflow can handle my unusual ${first} ${second} problem end to end`,
+    `Please guide me through a difficult unfamiliar ${first} ${second} operation safely`,
+  ];
+  return templates[variant % templates.length]!;
+}
+
+function ambiguousQuery(first: VaultSkill, second: VaultSkill): string {
+  const [firstAnchor = "first"] = anchors(first);
+  const [secondAnchor = "second"] = anchors(second);
+  return `Help with a workflow spanning both ${firstAnchor} and ${secondAnchor} responsibilities`;
+}
+
+function nearMissQuery(first: VaultSkill, second: VaultSkill): string {
+  const [firstAnchor = "one"] = anchors(first);
+  const [secondAnchor = "another"] = anchors(second);
+  return `Explain the theory comparing ${firstAnchor} and ${secondAnchor} without performing either workflow`;
+}
 
 /**
  * Automatically generate a synthetic decision-policy calibration dataset
@@ -30,110 +61,58 @@ export function generateDataset(
   skills: VaultSkill[],
   options: GenerateDatasetOptions = {},
 ): RawDecisionCase[] {
-  const cases: RawDecisionCase[] = [];
+  if (skills.length < 4) {
+    throw new Error(
+      "Dataset generation requires at least 4 vault skills so tune and test can each contain matched and ambiguous cases without skill leakage",
+    );
+  }
 
-  // --- 1. Matched Cases ---
-  for (const skill of skills) {
-    // Primary query from title + description
-    cases.push({
-      query: `how do I ${skill.title.toLowerCase()}: ${skill.description.toLowerCase()}`,
-      split: "tune",
-      expected_outcome: "matched",
-      relevant_skill_ids: [skill.skill_id],
-    });
+  const cases: RawDecisionCase[] = [];
+  const sorted = [...skills].sort((a, b) => a.skill_id.localeCompare(b.skill_id));
+  const splitAt = Math.ceil(sorted.length / 2);
+  const bySplit: Record<DecisionSplit, VaultSkill[]> = {
+    tune: sorted.slice(0, splitAt),
+    test: sorted.slice(splitAt),
+  };
+  const targetPerSplit = Math.max(3, options.queriesPerSplit ?? 10);
 
-    // Secondary query from aliases
-    if (skill.aliases.length > 0) {
-      cases.push({
-        query: `help me with ${skill.aliases[0]}`,
-        split: "test",
-        expected_outcome: "matched",
-        relevant_skill_ids: [skill.skill_id],
-      });
-    } else {
+  for (const split of ["tune", "test"] as const) {
+    const splitSkills = bySplit[split];
+    for (let i = 0; i < splitSkills.length; i++) {
+      const skill = splitSkills[i]!;
       cases.push({
-        query: `execute task related to ${skill.title}`,
-        split: "test",
+        query: matchedQuery(skill, i),
+        split,
         expected_outcome: "matched",
         relevant_skill_ids: [skill.skill_id],
       });
     }
-  }
 
-  // --- 2. Ambiguous Cases ---
-  if (skills.length >= 2) {
-    // Pair skills for ambiguous multi-match
-    for (let i = 0; i < skills.length - 1; i += 2) {
-      const s1 = skills[i]!;
-      const s2 = skills[i + 1]!;
-      const split: DecisionSplit = i % 4 === 0 ? "tune" : "test";
-      cases.push({
-        query: `automated task using ${s1.title} and ${s2.title}`,
-        split,
-        expected_outcome: "ambiguous",
-        relevant_skill_ids: [s1.skill_id, s2.skill_id],
-      });
-    }
-  } else {
-    // Fallback ambiguous cases if fewer than 2 skills
-    cases.push({
-      query: "automate browser workflow testing",
-      split: "tune",
-      expected_outcome: "ambiguous",
-      relevant_skill_ids: ["mock-e2e", "mock-browser"],
-    });
-    cases.push({
-      query: "extract and fetch clean web text",
-      split: "test",
-      expected_outcome: "ambiguous",
-      relevant_skill_ids: ["mock-fetch", "mock-extract"],
-    });
-  }
-
-  // Ensure both tune and test have ambiguous cases
-  if (!cases.some((c) => c.split === "tune" && c.expected_outcome === "ambiguous")) {
-    const sIds = skills.length >= 2 ? [skills[0]!.skill_id, skills[1]!.skill_id] : ["mock-a", "mock-b"];
+    const first = splitSkills[0]!;
+    const second = splitSkills[1]!;
     cases.push({
-      query: "integrated workflow multi skill query",
-      split: "tune",
+      query: ambiguousQuery(first, second),
+      split,
       expected_outcome: "ambiguous",
-      relevant_skill_ids: sIds,
+      relevant_skill_ids: [first.skill_id, second.skill_id],
     });
-  }
-  if (!cases.some((c) => c.split === "test" && c.expected_outcome === "ambiguous")) {
-    const sIds = skills.length >= 2 ? [skills[0]!.skill_id, skills[1]!.skill_id] : ["mock-a", "mock-b"];
     cases.push({
-      query: "combined operations multi skill query",
-      split: "test",
-      expected_outcome: "ambiguous",
-      relevant_skill_ids: sIds,
-    });
-  }
-
-  // --- 3. No Match Cases ---
-  GENERIC_NO_MATCH_QUERIES.forEach((q, idx) => {
-    cases.push({
-      query: q,
-      split: idx % 2 === 0 ? "tune" : "test",
+      query: nearMissQuery(first, second),
+      split,
       expected_outcome: "no_match",
       relevant_skill_ids: [],
     });
-  });
 
-  // Ensure both splits have at least 1 matched case if skills were empty
-  if (skills.length === 0) {
-    cases.push({
-      query: "run mock container action",
-      split: "tune",
-      expected_outcome: "matched",
-      relevant_skill_ids: ["mock-container"],
-    });
-    cases.push({
-      query: "search mock API docs",
-      split: "test",
-      expected_outcome: "matched",
-      relevant_skill_ids: ["mock-docs"],
-    });
+    for (let i = cases.filter((item) => item.split === split).length; i < targetPerSplit; i++) {
+      const left = splitSkills[i % splitSkills.length]!;
+      const right = splitSkills[(i + 1) % splitSkills.length]!;
+      cases.push({
+        query: i % 2 === 0 ? matchedQuery(left, i) : nearMissQuery(left, right),
+        split,
+        expected_outcome: i % 2 === 0 ? "matched" : "no_match",
+        relevant_skill_ids: i % 2 === 0 ? [left.skill_id] : [],
+      });
+    }
   }
 
   return cases;

package/src/decision.ts

@@ -23,7 +23,10 @@ export function decideResolveOutcome({ reranked, candidates, thresholds }: Decis
     || thresholds.match_margin === undefined
     || thresholds.candidate_floor === undefined
   ) {
-    throw new Error("Reranked decisions require calibrated thresholds.");
+    return {
+      outcome: "ambiguous",
+      candidates: candidates.slice(0, thresholds.candidate_limit),
+    };
   }
   const { match_score, match_margin, candidate_floor } = thresholds;
 

package/src/doctor.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { createClients } from "./clients";
+import { createClients, RemoteInferenceError } from "./clients";
 import { embeddingDimension, expandHome } from "./config";
 import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
@@ -10,6 +10,7 @@ export interface DoctorCheck {
   name: string;
   ok: boolean;
   detail: string;
+  failure_kind?: "configuration" | "availability" | "protocol" | "unexpected";
 }
 
 export interface DoctorReport {
@@ -99,8 +100,13 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
     }
   }
 
+  const inferenceFailure = (error: unknown): Pick<DoctorCheck, "detail" | "failure_kind"> =>
+    error instanceof RemoteInferenceError
+      ? { detail: error.message, failure_kind: error.kind }
+      : { detail: "unexpected inference failure", failure_kind: "unexpected" };
+
+  const clients = createClients(config);
   try {
-    const clients = createClients(config);
     const vectors = await clients.embed(["skill router diagnostic"]);
     const actualDimension = vectors[0]?.length ?? 0;
     checks.push({
@@ -108,14 +114,19 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
       ok: actualDimension === embeddingDimension(config),
       detail: `dimension ${actualDimension}`,
     });
-    if (clients.rerank) {
+  } catch (error) {
+    checks.push({ name: "embedding", ok: false, ...inferenceFailure(error) });
+  }
+
+  if (clients.rerank) {
+    try {
       const scores = await clients.rerank("skill router diagnostic", [
         { skill_id: "doctor", text: "Routes a task to an appropriate skill." },
       ]);
       checks.push({ name: "reranker", ok: scores.length === 1 && Number.isFinite(scores[0]), detail: "one finite score" });
+    } catch (error) {
+      checks.push({ name: "reranker", ok: false, ...inferenceFailure(error) });
     }
-  } catch (error) {
-    checks.push({ name: "inference", ok: false, detail: String(error) });
   }
 
   const inferenceReady = checks.some((check) => check.name === "embedding" && check.ok);

package/src/eval.ts

@@ -78,7 +78,8 @@ export async function evalVault(cases = loadEvalCases()): Promise<EvalReport> {
   const hybridRankings: string[][] = [];
   for (const evalCase of cases) {
     const lexical = ftsSearch(db, evalCase.query, config.recall.k_lexical);
-    const vector = (await clients.embed([evalCase.query]))[0]!;
+    const vector = (await clients.embed([evalCase.query]))[0];
+    if (!vector) throw new Error("Embedding client returned no query vector.");
     const semantic = vectorTopK(db, vector, config.recall.k_vector);
     lexicalRankings.push(lexical.map((row) => row.skill_id));
     hybridRankings.push(reciprocalRankFusion<SkillRow>(lexical, semantic).map((row) => row.skill_id));

package/src/router-core.ts

@@ -3,6 +3,7 @@ import { watch } from "node:fs";
 import { join } from "node:path";
 import { buildAuditRow } from "./audit";
 import { embeddingDimension, embeddingFingerprint, expandHome, loadConfig } from "./config";
+import { RemoteInferenceError } from "./clients";
 import {
   deleteSkill,
   findExactMatch,
@@ -269,12 +270,22 @@ export async function backfillEmbeddings(): Promise<number> {
     const chunk = pending.slice(i, i + BATCH_SIZE);
     try {
       const vectors = await clients.embed(chunk.map(rerankText));
-      chunk.forEach((row, j) => {
-        upsertVector(db, row.skill_id, row.content_sha256, fingerprint, vectors[j]!);
-      });
+      db.transaction(() => {
+        chunk.forEach((row, j) => {
+          const vector = vectors[j];
+          if (!vector) throw new Error("Embedding client returned an incomplete batch.");
+          upsertVector(db, row.skill_id, row.content_sha256, fingerprint, vector);
+        });
+      })();
       count += chunk.length;
     } catch (err) {
-      if (i === 0) throw err;
+      if (
+        i === 0 ||
+        (err instanceof RemoteInferenceError &&
+          (err.kind === "configuration" || err.kind === "protocol"))
+      ) {
+        throw err;
+      }
       break;
     }
   }
@@ -384,44 +395,7 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
     return result;
   }
 
-  const clients = getClients();
-
-  const lexical = ftsSearch(db, input.query, config.recall.k_lexical);
-
-  let retrieval: RetrievalCapability = "lexical";
-  let rows = lexical;
-  if (!input.forceLexical) {
-    try {
-      const queryVec = (await clients.embed([input.query]))[0]!;
-      const nearest = vectorTopK(db, queryVec, config.recall.k_vector);
-      rows = reciprocalRankFusion(lexical, nearest);
-      retrieval = "hybrid";
-    } catch {
-      retrieval = "lexical";
-    }
-  }
-
-  let scores: number[] | null = null;
-  if (clients.rerank && retrieval === "hybrid" && rows.length > 0) {
-    try {
-      scores = await clients.rerank(
-        input.query,
-        rows.map((r) => ({ skill_id: r.skill_id, text: rerankText(r) })),
-      );
-      retrieval = "reranked";
-    } catch {
-      scores = null;
-    }
-  }
-
-  const rankedCandidates: RankedCandidate[] = rows
-    .map((r, i) => ({
-      skill_id: r.skill_id,
-      title: r.title,
-      description: r.description,
-      score: scores?.[i] ?? null,
-    }))
-    .sort((a, b) => scores === null ? 0 : (b.score ?? -Infinity) - (a.score ?? -Infinity));
+  const { retrieval, candidates: rankedCandidates } = await retrieveAndRerank(input);
 
   const decisionThresholds = retrieval === "reranked" && config.inference.mode === "remote"
     ? { candidate_limit: config.thresholds.candidate_limit, ...config.inference.thresholds }
@@ -473,6 +447,63 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
   return result;
 }
 
+export interface RetrievalResult {
+  retrieval: Exclude<RetrievalCapability, "exact">;
+  candidates: RankedCandidate[];
+}
+
+/**
+ * Retrieve the full fused candidate set and rerank it once without applying
+ * decision thresholds. Calibration uses this to avoid observing the policy it
+ * is trying to replace.
+ */
+export async function retrieveAndRerank(
+  input: ResolveSkillInput,
+): Promise<RetrievalResult> {
+  const { config, db } = await getEnv();
+  await syncVaultIfNeeded();
+  const clients = getClients();
+  const lexical = ftsSearch(db, input.query, config.recall.k_lexical);
+
+  let retrieval: RetrievalResult["retrieval"] = "lexical";
+  let rows = lexical;
+  if (!input.forceLexical) {
+    try {
+      const queryVec = (await clients.embed([input.query]))[0];
+      if (!queryVec) throw new Error("Embedding client returned no query vector.");
+      const nearest = vectorTopK(db, queryVec, config.recall.k_vector);
+      rows = reciprocalRankFusion(lexical, nearest);
+      retrieval = "hybrid";
+    } catch {
+      retrieval = "lexical";
+    }
+  }
+
+  let scores: number[] | null = null;
+  if (clients.rerank && retrieval === "hybrid" && rows.length > 0) {
+    try {
+      scores = await clients.rerank(
+        input.query,
+        rows.map((r) => ({ skill_id: r.skill_id, text: rerankText(r) })),
+      );
+      retrieval = "reranked";
+    } catch {
+      scores = null;
+    }
+  }
+
+  const candidates = rows
+    .map((r, i) => ({
+      skill_id: r.skill_id,
+      title: r.title,
+      description: r.description,
+      score: scores?.[i] ?? null,
+    }))
+    .sort((a, b) => scores === null ? 0 : (b.score ?? -Infinity) - (a.score ?? -Infinity));
+
+  return { retrieval, candidates };
+}
+
 export async function fetchSkill(input: FetchSkillInput): Promise<FetchSkillResult> {
   const { config, db } = await getEnv();
   await syncVaultIfNeeded();