@klhapp/skillmux 0.2.0

package/src/config.ts

@@ -0,0 +1,338 @@
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import type { Config, ONNXDevice, ONNXDtype } from "./types";
+
+const onnxDeviceSchema = z.enum([
+  "cpu", "auto", "gpu", "wasm", "webgpu", "cuda", "dml", "coreml",
+  "webnn", "webnn-npu", "webnn-gpu", "webnn-cpu",
+]);
+const onnxDtypeSchema = z.enum([
+  "q8", "auto", "fp32", "fp16", "int8", "uint8", "q4", "bnb4", "q4f16",
+  "q2", "q2f16", "q1", "q1f16",
+]);
+
+const modelSchema = z.object({
+  model: z.string().min(1),
+  device: onnxDeviceSchema.optional(),
+  dtype: onnxDtypeSchema.optional(),
+}).strict();
+
+const remoteThresholdsSchema = z.object({
+  match_score: z.number(),
+  match_margin: z.number().nonnegative(),
+  candidate_floor: z.number(),
+}).strict();
+
+const configSchema = z.object({
+  vault_path: z.string().min(1),
+  state_dir: z.string().min(1),
+  recall: z.object({ k_lexical: z.number().int().positive(), k_vector: z.number().int().positive() }).strict(),
+  thresholds: z.object({
+    candidate_limit: z.number().int().positive(),
+    match_score: z.number().optional(),
+    match_margin: z.number().nonnegative().optional(),
+    candidate_floor: z.number().optional(),
+  }).strict(),
+  inference: z.discriminatedUnion("mode", [
+    z.object({
+      mode: z.literal("local"),
+      bundle: z.string().min(1),
+      models_dir: z.string().min(1),
+      embedding: modelSchema.extend({ dimension: z.number().int().positive() }),
+    }).strict(),
+    z.object({
+      mode: z.literal("remote"),
+      timeout_ms: z.number().int().min(100),
+      embedding: z.object({
+        provider: z.literal("openai"),
+        base_url: 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(),
+        model: z.string().min(1),
+        api_key_env: z.string().min(1).optional(),
+      }).strict().optional(),
+      thresholds: remoteThresholdsSchema.optional(),
+    }).strict(),
+  ]),
+  server: z.object({
+    auth_enabled: z.boolean(),
+    auth_token_env: z.string().min(1),
+    allowed_origins: z.array(z.string()),
+    hostname: z.string().min(1).optional(),
+    rate_limit: z.object({
+      enabled: z.boolean(),
+      requests_per_minute: z.number().int().positive(),
+      trust_proxy: z.boolean().optional(),
+    }).strict().optional(),
+  }).strict().optional(),
+}).strict();
+
+// Fallback values only; a config.toml (SKILLMUX_CONFIG or default path)
+// overrides them. The local bundle is the zero-config OSS path.
+export const LOCAL_BUNDLE_ID = "gte-small-v1";
+
+const DEFAULTS: Config = {
+  vault_path: "~/skills",
+  state_dir: "~/.local/state/skillmux",
+  recall: { k_lexical: 20, k_vector: 20 },
+  thresholds: { candidate_limit: 5 },
+  inference: {
+    mode: "local",
+    bundle: LOCAL_BUNDLE_ID,
+    models_dir: "~/.cache/skillmux/models",
+    embedding: {
+      model: "Xenova/gte-small",
+      dimension: 384,
+      device: "cpu",
+      dtype: "q8",
+    },
+  },
+  server: {
+    auth_enabled: false,
+    auth_token_env: "SKILLMUX_AUTH_TOKEN",
+    // Deny-by-default CORS: only requests that send no Origin header (curl,
+    // MCP clients, server-to-server) pass; browser-issued cross-origin
+    // requests are rejected until an origin is explicitly allow-listed.
+    allowed_origins: [],
+    // Loopback-only by default so a zero-config `skillmux serve --transport http`
+    // isn't reachable from the network. Docker overrides this to 0.0.0.0
+    // below since the container's own loopback isn't reachable through
+    // port-mapping.
+    hostname: "127.0.0.1",
+    rate_limit: {
+      enabled: false,
+      requests_per_minute: 60,
+    },
+  },
+};
+
+export const DEFAULT_CONFIG_PATH = "~/.config/skillmux/config.toml";
+
+export function embeddingDimension(config: Config): number {
+  return config.inference.embedding.dimension;
+}
+
+export function embeddingFingerprint(config: Config): string {
+  const inference = config.inference;
+  const implementation =
+    inference.mode === "local" ? `local:${inference.bundle}` : `remote:${inference.embedding.provider}`;
+  return `${implementation}:${inference.embedding.model}:${inference.embedding.dimension}`;
+}
+
+export function expandHome(path: string): string {
+  return path.startsWith("~") ? join(homedir(), path.slice(1)) : path;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function deepMerge<T>(base: T, override: unknown): T {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return (override === undefined ? base : override) as T;
+  }
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    out[key] = deepMerge((base as Record<string, unknown>)[key], value);
+  }
+  return out as T;
+}
+
+export const warnedEnv = new Set<string>();
+
+function migrateLegacyDir(legacy: string, next: string): void {
+  const legacyPath = expandHome(legacy);
+  const nextPath = expandHome(next);
+  if (existsSync(nextPath) || !existsSync(legacyPath)) return;
+  mkdirSync(dirname(nextPath), { recursive: true });
+  renameSync(legacyPath, nextPath);
+  console.error(`skillmux: migrated ${legacyPath} -> ${nextPath}`);
+}
+
+export function migrateLegacyPaths(): void {
+  migrateLegacyDir("~/.config/skill-router", "~/.config/skillmux");
+  migrateLegacyDir("~/.local/state/skill-router", "~/.local/state/skillmux");
+  migrateLegacyDir("~/.cache/skill-router", "~/.cache/skillmux");
+}
+
+export async function loadConfig(path?: string): Promise<Config> {
+  migrateLegacyPaths();
+  let configEnv = process.env.SKILLMUX_CONFIG;
+  if (configEnv === undefined && process.env.SKILL_ROUTER_CONFIG !== undefined) {
+    if (!warnedEnv.has("SKILL_ROUTER_CONFIG")) {
+      warnedEnv.add("SKILL_ROUTER_CONFIG");
+      console.error("skillmux: SKILL_ROUTER_CONFIG is deprecated, use SKILLMUX_CONFIG instead");
+    }
+    configEnv = process.env.SKILL_ROUTER_CONFIG;
+  }
+  const configPath = path ?? configEnv ?? DEFAULT_CONFIG_PATH;
+  const file = Bun.file(expandHome(configPath));
+
+  const baseConfig = structuredClone(DEFAULTS);
+  if (process.env.RUNNING_IN_DOCKER === "true") {
+    baseConfig.vault_path = "/vault";
+    baseConfig.state_dir = "/data";
+    if (baseConfig.inference.mode === "local") baseConfig.inference.models_dir = "/models";
+    if (baseConfig.server) baseConfig.server.hostname = "0.0.0.0";
+  }
+
+  let merged: Config;
+  if (!(await file.exists())) {
+    merged = baseConfig;
+  } else {
+    const parsed = Bun.TOML.parse(await file.text()) as Record<string, unknown>;
+    if ("embedding" in parsed || "rerank" in parsed || "remote_timeout_ms" in parsed) {
+      throw new Error(
+        "Legacy inference config is not supported. Move [embedding], [rerank], and remote_timeout_ms under [inference] using config.remote.example.toml.",
+      );
+    }
+    if (isPlainObject(parsed.inference) && parsed.inference.mode === "remote") {
+      if (!isPlainObject(parsed.inference.embedding)) {
+        throw new Error("Remote inference requires an inference.embedding section.");
+      }
+      const withoutInference = { ...parsed };
+      delete withoutInference.inference;
+      merged = {
+        ...deepMerge(baseConfig, withoutInference),
+        inference: configSchema.shape.inference.parse(parsed.inference),
+      };
+    } else {
+      merged = deepMerge(baseConfig, parsed);
+    }
+  }
+
+  // Environment variable overrides.
+  if (process.env.VAULT_PATH) {
+    merged.vault_path = process.env.VAULT_PATH;
+  }
+  if (process.env.STATE_DIR) {
+    merged.state_dir = process.env.STATE_DIR;
+  }
+  const getEnv = (newPrefixed: string, unprefixed: string) => {
+    const legacyPrefixed = newPrefixed.replace(/^SKILLMUX_/, "SKILL_ROUTER_");
+    if (process.env[newPrefixed] !== undefined) return process.env[newPrefixed];
+    if (process.env[legacyPrefixed] !== undefined) {
+      if (!warnedEnv.has(legacyPrefixed)) {
+        warnedEnv.add(legacyPrefixed);
+        console.error(`skillmux: ${legacyPrefixed} is deprecated, use ${newPrefixed} instead`);
+      }
+      return process.env[legacyPrefixed];
+    }
+    return process.env[unprefixed];
+  };
+
+  if (merged.inference.mode === "local") {
+    let modelsDirEnv = process.env.SKILLMUX_MODELS_DIR;
+    if (modelsDirEnv === undefined && process.env.SKILL_ROUTER_MODELS_DIR !== undefined) {
+      if (!warnedEnv.has("SKILL_ROUTER_MODELS_DIR")) {
+        warnedEnv.add("SKILL_ROUTER_MODELS_DIR");
+        console.error("skillmux: SKILL_ROUTER_MODELS_DIR is deprecated, use SKILLMUX_MODELS_DIR instead");
+      }
+      modelsDirEnv = process.env.SKILL_ROUTER_MODELS_DIR;
+    }
+    if (modelsDirEnv) merged.inference.models_dir = modelsDirEnv;
+    if (process.env.EMBED_DEVICE) merged.inference.embedding.device = process.env.EMBED_DEVICE as ONNXDevice;
+    if (process.env.EMBED_DTYPE) merged.inference.embedding.dtype = process.env.EMBED_DTYPE as ONNXDtype;
+  } else if (merged.inference.mode === "remote") {
+    if (!merged.inference.embedding) {
+      throw new Error("Remote inference requires an inference.embedding section.");
+    }
+    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.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.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 embedUrl = getEnv("SKILLMUX_EMBED_BASE_URL", "EMBED_BASE_URL");
+    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 rerankModel = getEnv("SKILLMUX_RERANK_MODEL", "RERANK_MODEL");
+    if (embedUrl) merged.inference.embedding.base_url = embedUrl;
+    if (embedModel) merged.inference.embedding.model = embedModel;
+    if (rerankUrl && merged.inference.reranker) merged.inference.reranker.base_url = rerankUrl;
+    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;
+    }
+  } else {
+    throw new Error(`Invalid inference.mode: ${(merged.inference as { mode?: unknown }).mode}`);
+  }
+
+  // HTTP server environment overrides
+  if (merged.server) {
+    if (process.env.HTTP_AUTH_ENABLED) {
+      merged.server.auth_enabled = process.env.HTTP_AUTH_ENABLED === "true";
+    }
+    if (process.env.HTTP_AUTH_TOKEN_ENV) {
+      merged.server.auth_token_env = process.env.HTTP_AUTH_TOKEN_ENV;
+    }
+    if (process.env.HTTP_ALLOWED_ORIGINS) {
+      merged.server.allowed_origins = process.env.HTTP_ALLOWED_ORIGINS.split(",").map((o) => o.trim());
+    }
+    if (process.env.HTTP_HOSTNAME) {
+      merged.server.hostname = process.env.HTTP_HOSTNAME;
+    }
+
+    if (!merged.server.rate_limit) {
+      merged.server.rate_limit = { enabled: false, requests_per_minute: 60 };
+    }
+
+    const rateLimitEnabledStr = getEnv("SKILLMUX_HTTP_RATE_LIMIT_ENABLED", "HTTP_RATE_LIMIT_ENABLED");
+    if (rateLimitEnabledStr) {
+      merged.server.rate_limit.enabled = rateLimitEnabledStr === "true";
+    }
+
+    const rateLimitRPMStr = getEnv("SKILLMUX_HTTP_RATE_LIMIT_RPM", "HTTP_RATE_LIMIT_RPM");
+    if (rateLimitRPMStr) {
+      const rpm = Number(rateLimitRPMStr);
+      if (!Number.isInteger(rpm)) {
+        throw new Error(`Invalid rate limit RPM: ${rateLimitRPMStr}`);
+      }
+      merged.server.rate_limit.requests_per_minute = rpm;
+    }
+
+    const rateLimitTrustProxyStr = getEnv("SKILLMUX_HTTP_RATE_LIMIT_TRUST_PROXY", "HTTP_RATE_LIMIT_TRUST_PROXY");
+    if (rateLimitTrustProxyStr) {
+      merged.server.rate_limit.trust_proxy = rateLimitTrustProxyStr === "true";
+    }
+
+    if (merged.server.rate_limit.enabled && merged.server.rate_limit.requests_per_minute === undefined) {
+      merged.server.rate_limit.requests_per_minute = 60;
+    }
+  }
+
+  return configSchema.parse(merged) as Config;
+}

package/src/db.ts

@@ -0,0 +1,280 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { AuditCandidate, AuditRow } from "./types";
+import type { VaultSkill } from "./vault";
+
+export interface SkillRow {
+  skill_id: string;
+  title: string;
+  description: string;
+  aliases: string;
+  content_sha256: string;
+}
+
+export function openIndex(stateDir: string): Database {
+  mkdirSync(stateDir, { recursive: true });
+  const db = new Database(join(stateDir, "index.sqlite3"), { create: true });
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA busy_timeout = 2000");
+  db.run(`CREATE TABLE IF NOT EXISTS skills (
+    skill_id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL,
+    aliases TEXT NOT NULL,
+    content_sha256 TEXT NOT NULL
+  )`);
+  db.run(`CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5(
+    skill_id UNINDEXED, title, description, aliases,
+    tokenize = 'unicode61 remove_diacritics 2'
+  )`);
+  db.run(`CREATE TABLE IF NOT EXISTS vectors (
+    skill_id TEXT PRIMARY KEY,
+    content_sha256 TEXT NOT NULL,
+    embedding_fingerprint TEXT NOT NULL DEFAULT '',
+    dim INTEGER NOT NULL,
+    vec BLOB NOT NULL
+  )`);
+  const vectorColumns = db.query("PRAGMA table_info(vectors)").all() as { name: string }[];
+  if (!vectorColumns.some((column) => column.name === "embedding_fingerprint")) {
+    db.run("ALTER TABLE vectors ADD COLUMN embedding_fingerprint TEXT NOT NULL DEFAULT ''");
+  }
+  db.run(`CREATE TABLE IF NOT EXISTS audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL,
+    query TEXT NOT NULL,
+    outcome TEXT NOT NULL CHECK (outcome IN ('matched', 'ambiguous', 'no_match')),
+    degraded INTEGER NOT NULL,
+    retrieval TEXT NOT NULL DEFAULT 'lexical',
+    candidates TEXT NOT NULL,
+    selected_skill_id TEXT,
+    latency_ms INTEGER NOT NULL
+  )`);
+  const auditColumns = db.query("PRAGMA table_info(audit)").all() as { name: string }[];
+  if (!auditColumns.some((column) => column.name === "retrieval")) {
+    db.run("ALTER TABLE audit ADD COLUMN retrieval TEXT NOT NULL DEFAULT 'lexical'");
+  }
+  db.run(`CREATE TABLE IF NOT EXISTS index_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  )`);
+  return db;
+}
+
+export function upsertSkill(db: Database, skill: VaultSkill): void {
+  const aliases = skill.aliases.join(" ");
+  db.transaction(() => {
+    db.run("DELETE FROM skills WHERE skill_id = ?", [skill.skill_id]);
+    db.run("DELETE FROM skills_fts WHERE skill_id = ?", [skill.skill_id]);
+    db.run(
+      "INSERT INTO skills (skill_id, title, description, aliases, content_sha256) VALUES (?, ?, ?, ?, ?)",
+      [skill.skill_id, skill.title, skill.description, aliases, skill.content_sha256],
+    );
+    db.run(
+      "INSERT INTO skills_fts (skill_id, title, description, aliases) VALUES (?, ?, ?, ?)",
+      [skill.skill_id, skill.title, skill.description, aliases],
+    );
+  })();
+}
+
+export function toSkillRow(skill: VaultSkill): SkillRow {
+  return {
+    skill_id: skill.skill_id,
+    title: skill.title,
+    description: skill.description,
+    aliases: skill.aliases.join(" "),
+    content_sha256: skill.content_sha256,
+  };
+}
+
+/** Replace the whole lexical index with `rows`; drops vectors of removed skills. */
+export function replaceSkills(db: Database, rows: SkillRow[]): void {
+  db.transaction(() => {
+    db.run("DELETE FROM skills");
+    db.run("DELETE FROM skills_fts");
+    for (const row of rows) {
+      db.run(
+        "INSERT INTO skills (skill_id, title, description, aliases, content_sha256) VALUES (?, ?, ?, ?, ?)",
+        [row.skill_id, row.title, row.description, row.aliases, row.content_sha256],
+      );
+      db.run(
+        "INSERT INTO skills_fts (skill_id, title, description, aliases) VALUES (?, ?, ?, ?)",
+        [row.skill_id, row.title, row.description, row.aliases],
+      );
+    }
+    db.run("DELETE FROM vectors WHERE skill_id NOT IN (SELECT skill_id FROM skills)");
+  })();
+}
+
+export function ingestVault(db: Database, skills: VaultSkill[]): void {
+  replaceSkills(db, skills.map(toSkillRow));
+}
+
+export function deleteSkill(db: Database, skillId: string): void {
+  db.transaction(() => {
+    db.run("DELETE FROM skills WHERE skill_id = ?", [skillId]);
+    db.run("DELETE FROM skills_fts WHERE skill_id = ?", [skillId]);
+    db.run("DELETE FROM vectors WHERE skill_id = ?", [skillId]);
+  })();
+}
+
+export function skillCount(db: Database): number {
+  return (db.query("SELECT count(*) AS n FROM skills").get() as { n: number }).n;
+}
+
+export function getSkillRow(db: Database, skillId: string): SkillRow | null {
+  return db.query("SELECT * FROM skills WHERE skill_id = ?").get(skillId) as SkillRow | null;
+}
+
+/**
+ * Sanitize free text into an FTS5 OR-query; returns null when no usable terms
+ * remain. Terms keep any Unicode letters/digits (CJK included) so non-ASCII
+ * queries still get lexical recall — unicode61 tokenizes contiguous CJK runs
+ * as single tokens, so matching works at that granularity.
+ */
+export function toFtsQuery(text: string): string | null {
+  const terms = [
+    ...new Set(
+      text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => t.length >= 2),
+    ),
+  ];
+  if (terms.length === 0) return null;
+  return terms.map((t) => `"${t}"`).join(" OR ");
+}
+
+export function ftsSearch(db: Database, text: string, k: number): SkillRow[] {
+  const query = toFtsQuery(text);
+  if (query === null) return [];
+  return db
+    .query(
+      `SELECT s.* FROM skills_fts f
+       JOIN skills s ON s.skill_id = f.skill_id
+       WHERE skills_fts MATCH ?
+       ORDER BY bm25(skills_fts) LIMIT ?`,
+    )
+    .all(query, k) as SkillRow[];
+}
+
+export function findExactMatch(db: Database, query: string): SkillRow | null {
+  const cleanQuery = query.trim().toLowerCase();
+  return db
+    .query(
+      `SELECT * FROM skills 
+       WHERE lower(skill_id) = ? 
+          OR lower(title) = ? 
+          OR ' ' || lower(aliases) || ' ' LIKE ?`,
+    )
+    .get(cleanQuery, cleanQuery, `% ${cleanQuery} %`) as SkillRow | null;
+}
+
+export function getIndexMeta(db: Database, key: string): string | null {
+  const row = db
+    .query("SELECT value FROM index_meta WHERE key = ?")
+    .get(key) as { value: string } | null;
+  return row ? row.value : null;
+}
+
+export function setIndexMeta(db: Database, key: string, value: string): void {
+  db.run(
+    `INSERT INTO index_meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+    [key, value],
+  );
+}
+
+export function upsertVector(
+  db: Database,
+  skillId: string,
+  contentSha256: string,
+  embeddingFingerprint: string,
+  vec: Float32Array,
+): void {
+  db.run(
+    `INSERT INTO vectors (skill_id, content_sha256, embedding_fingerprint, dim, vec) VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(skill_id) DO UPDATE SET
+       content_sha256 = excluded.content_sha256,
+       embedding_fingerprint = excluded.embedding_fingerprint,
+       dim = excluded.dim,
+       vec = excluded.vec`,
+    [skillId, contentSha256, embeddingFingerprint, vec.length, new Uint8Array(vec.buffer, vec.byteOffset, vec.byteLength)],
+  );
+}
+
+/**
+ * Skills with no usable stored vector: none at all, content changed since
+ * embedding, or embedded at a different dimension than currently configured.
+ */
+export function skillsNeedingVectors(db: Database, dimension: number, embeddingFingerprint: string): SkillRow[] {
+  return db
+    .query(
+      `SELECT s.* FROM skills s
+       LEFT JOIN vectors v ON v.skill_id = s.skill_id
+          AND v.content_sha256 = s.content_sha256
+          AND v.dim = ?
+          AND v.embedding_fingerprint = ?
+        WHERE v.skill_id IS NULL`,
+    )
+    .all(dimension, embeddingFingerprint) as SkillRow[];
+}
+
+function cosine(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+/** Brute-force cosine over every stored vector (vault is ~100 skills; no ANN). */
+export function vectorTopK(db: Database, query: Float32Array, k: number): SkillRow[] {
+  const rows = db
+    .query(
+      `SELECT s.skill_id, s.title, s.description, s.aliases, s.content_sha256, v.vec
+       FROM vectors v JOIN skills s ON s.skill_id = v.skill_id`,
+    )
+    .all() as (SkillRow & { vec: Uint8Array })[];
+  return rows
+    .map(({ vec, ...row }) => ({
+      row,
+      score: cosine(query, new Float32Array(vec.buffer, vec.byteOffset, vec.byteLength / 4)),
+    }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, k)
+    .map((r) => r.row);
+}
+
+export interface AuditInsert {
+  ts: string;
+  query: string;
+  outcome: string;
+  retrieval: AuditRow["retrieval"];
+  candidates: AuditCandidate[];
+  selected_skill_id: string | null;
+  latency_ms: number;
+}
+
+export function insertAudit(db: Database, row: AuditInsert): void {
+  db.run(
+    `INSERT INTO audit (ts, query, outcome, degraded, retrieval, candidates, selected_skill_id, latency_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      row.ts,
+      row.query,
+      row.outcome,
+      row.retrieval === "lexical" ? 1 : 0,
+      row.retrieval,
+      JSON.stringify(row.candidates),
+      row.selected_skill_id,
+      row.latency_ms,
+    ],
+  );
+}

package/src/decision.ts

@@ -0,0 +1,42 @@
+import type { RankedCandidate, Thresholds } from "./types";
+
+export interface DecisionInput {
+  reranked: boolean;
+  candidates: RankedCandidate[];
+  thresholds: Thresholds;
+}
+
+export type Decision =
+  | { outcome: "matched"; skill_id: string; score: number; margin: number }
+  | { outcome: "ambiguous"; candidates: RankedCandidate[] }
+  | { outcome: "no_match" };
+
+export function decideResolveOutcome({ reranked, candidates, thresholds }: DecisionInput): Decision {
+  if (candidates.length === 0) return { outcome: "no_match" };
+
+  // Degraded lane: no comparable scores exist, so never match; the (BM25-ordered)
+  // Without calibrated reranker scores, the shortlist goes to the calling LLM.
+  if (!reranked) return { outcome: "ambiguous", candidates: candidates.slice(0, thresholds.candidate_limit) };
+
+  if (
+    thresholds.match_score === undefined
+    || thresholds.match_margin === undefined
+    || thresholds.candidate_floor === undefined
+  ) {
+    throw new Error("Reranked decisions require calibrated thresholds.");
+  }
+  const { match_score, match_margin, candidate_floor } = thresholds;
+
+  const sorted = [...candidates].sort((a, b) => (b.score ?? -Infinity) - (a.score ?? -Infinity));
+  const eligible = sorted.filter((c) => (c.score ?? -Infinity) >= candidate_floor);
+  if (eligible.length === 0) return { outcome: "no_match" };
+
+  const top = eligible[0]!;
+  const topScore = top.score!;
+  const margin = sorted.length === 1 ? topScore : topScore - (sorted[1]!.score ?? 0);
+
+  if (topScore >= match_score && margin >= match_margin) {
+    return { outcome: "matched", skill_id: top.skill_id, score: topScore, margin };
+  }
+  return { outcome: "ambiguous", candidates: eligible.slice(0, thresholds.candidate_limit) };
+}