lurqrun 0.1.6 → 0.1.7

package/dist/chunk-BULZAX2U.js

@@ -0,0 +1,1554 @@
+import { createRequire as __lurqCreateRequire } from 'node:module'; const require = __lurqCreateRequire(import.meta.url);
+import {
+  assessVerdict
+} from "./chunk-QSL6QN5X.js";
+import {
+  getStoredSurface,
+  upsertSurface
+} from "./chunk-M6NYEXCW.js";
+import {
+  getLatestVerificationByName
+} from "./chunk-6L3U7DZ5.js";
+import {
+  getStackResolution,
+  recordStackResolution,
+  resolveSet,
+  stackKey
+} from "./chunk-J5FZYN4A.js";
+import {
+  applyPolicy,
+  check,
+  describeRules,
+  diffPolicies,
+  hasRules,
+  withoutExpired
+} from "./chunk-PSX3GIAN.js";
+import {
+  FIRST_TOUCH_BUDGET_MS,
+  assembleMembers,
+  computeComposite,
+  createEmbeddingProvider,
+  fetchWeeklyDownloads,
+  getOrFetchPackage,
+  inferCategory,
+  loadLearnedSuccessors,
+  lookupSuccessor,
+  recordOutcome,
+  truncateSentences
+} from "./chunk-FW6BD2NO.js";
+import {
+  resolveArchitectureCompat,
+  resolveRuntimeEngineConflicts
+} from "./chunk-BUALU27S.js";
+import {
+  CONFIDENCE_WEIGHT,
+  RANKING,
+  loadWeights
+} from "./chunk-2VMOWSRY.js";
+import {
+  withBudget
+} from "./chunk-4ESO33J6.js";
+import {
+  enqueueCompatVerify,
+  getSandboxEdges,
+  pairKey
+} from "./chunk-CW5HJ3LX.js";
+import {
+  fetchNpmCompatAtVersion,
+  fetchNpmRegistry,
+  npmPackageExists,
+  npmVersionExists
+} from "./chunk-AHBP533R.js";
+import {
+  HttpError,
+  httpRequest
+} from "./chunk-SJOVFF7B.js";
+import {
+  cached
+} from "./chunk-HWBBVLOT.js";
+import {
+  getPackageByName,
+  getTopPackageNames
+} from "./chunk-NH5I4KHH.js";
+import {
+  DEFAULT_ECOSYSTEM
+} from "./chunk-VLRHFMGJ.js";
+import {
+  packages,
+  policyDecisions,
+  selectionPolicies,
+  selectionPolicyChanges
+} from "./chunk-LYMPYETA.js";
+import {
+  logger
+} from "./chunk-MYGSLK44.js";
+import {
+  CACHE_TTL,
+  STALENESS_DAYS
+} from "./chunk-GPTKSNR6.js";
+import {
+  init_esm_shims
+} from "./chunk-I3M2KJXB.js";
+
+// src/mcp/handlers.ts
+init_esm_shims();
+import { createHash } from "crypto";
+import { sql as sql3 } from "drizzle-orm";
+
+// src/compat/check.ts
+init_esm_shims();
+function gradeOverall(args) {
+  if (args.hasConflict || args.resolution === "conflict") return "conflict";
+  if (args.hasUnverifiedMember || args.resolution === "inconclusive") return "unknown";
+  return "compatible";
+}
+async function checkCompat(db, packages2, opts = {}) {
+  const names = [...new Set(packages2)];
+  const refs = names.map((name) => ({
+    name,
+    version: opts.versions?.[name] ?? null
+  }));
+  const { members, unverified } = await assembleMembers(db, refs);
+  const conflicts = [
+    ...resolveArchitectureCompat(members),
+    ...opts.node ? resolveRuntimeEngineConflicts(members, opts.node) : []
+  ];
+  const edges = await getSandboxEdges(db, names);
+  const versionOf = new Map(members.map((m) => [m.name, m.version]));
+  const evidence = edges.map((edge) => ({
+    packages: [edge.packageA, edge.packageB],
+    versions: [edge.versionA, edge.versionB],
+    status: edge.status,
+    provenance: edge.provenance,
+    witnessCount: edge.witnessCount
+  }));
+  for (const edge of edges) {
+    if (edge.status !== "conflict") continue;
+    const at = edgeMatchesVersions(edge, versionOf) ? "" : ` (recorded at those versions; you are checking ${edge.packageA}@${versionOf.get(edge.packageA) ?? "?"} and ${edge.packageB}@${versionOf.get(edge.packageB) ?? "?"})`;
+    conflicts.push({
+      source: "sandbox",
+      packages: [edge.packageA, edge.packageB],
+      detail: `${edge.packageA}@${edge.versionA} and ${edge.packageB}@${edge.versionB} failed to co-install in the sandbox${at}`
+    });
+  }
+  const checkedNames = members.map((m) => m.name);
+  const { resolution, verdict } = await settle(db, members, {
+    // A declared conflict is already proof. Paying npm to re-confirm it would be
+    // seconds spent learning nothing.
+    skip: conflicts.length > 0,
+    cachedOnly: opts.cachedOnly === true,
+    hasUnverified: unverified.length > 0
+  });
+  if (resolution?.reason === "ERESOLVE") {
+    conflicts.push({
+      source: "resolve",
+      packages: checkedNames,
+      detail: resolution.detail ?? "npm could not resolve this set together"
+    });
+  }
+  return {
+    packages: names,
+    overall: gradeOverall({
+      hasConflict: conflicts.length > 0,
+      hasUnverifiedMember: unverified.length > 0,
+      resolution: verdict
+    }),
+    conflicts,
+    unverified,
+    checked: members.map((m) => ({ name: m.name, version: m.version })),
+    evidence,
+    ...resolution ? { resolution } : {},
+    pairs: enumeratePairs(checkedNames, conflicts)
+  };
+}
+async function settle(db, members, opts) {
+  if (opts.skip) return { resolution: null, verdict: "inconclusive" };
+  const pinned = [];
+  for (const m of members) {
+    if (!m.version) return { resolution: null, verdict: "inconclusive" };
+    pinned.push({ name: m.name, version: m.version });
+  }
+  if (pinned.length < 2) return { resolution: null, verdict: "resolved" };
+  const key = stackKey(pinned);
+  const cached2 = await getStackResolution(db, key).catch(() => null);
+  if (cached2) {
+    return {
+      resolution: {
+        source: "cache",
+        resolved: cached2.resolved,
+        reason: cached2.reason === "ERESOLVE" ? "ERESOLVE" : null,
+        ...cached2.detail ? { detail: cached2.detail } : {},
+        at: cached2.resolvedAt.toISOString()
+      },
+      verdict: cached2.resolved ? "resolved" : "conflict"
+    };
+  }
+  if (opts.cachedOnly) return { resolution: null, verdict: "inconclusive" };
+  let result;
+  try {
+    result = await resolveSet(pinned);
+  } catch (err) {
+    logger.warn(`compat: resolve inconclusive for ${key}: ${String(err)}`);
+    return { resolution: null, verdict: "inconclusive" };
+  }
+  await recordStackResolution(db, {
+    members: pinned,
+    resolved: result.resolved,
+    reason: result.reason,
+    detail: result.detail ?? null
+  }).catch((err) => logger.warn(`compat: caching resolution failed: ${String(err)}`));
+  if (result.resolved) {
+    await enqueueCompatVerify(
+      db,
+      pinned.map((m) => m.name)
+    ).catch(() => {
+    });
+  }
+  return {
+    resolution: {
+      source: "resolved",
+      resolved: result.resolved,
+      reason: result.reason,
+      ...result.detail ? { detail: result.detail } : {},
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    verdict: result.resolved ? "resolved" : "conflict"
+  };
+}
+function edgeMatchesVersions(edge, versionOf) {
+  const a = versionOf.get(edge.packageA);
+  const b = versionOf.get(edge.packageB);
+  return a != null && b != null && a === edge.versionA && b === edge.versionB;
+}
+function enumeratePairs(names, conflicts) {
+  const byPair = /* @__PURE__ */ new Map();
+  for (const c of conflicts) {
+    if (c.source === "resolve") continue;
+    const [a, b] = c.packages;
+    if (!a || !b) continue;
+    const key = pairKey(a, b);
+    if (!byPair.has(key)) byPair.set(key, c);
+  }
+  const pairs = [];
+  for (let i = 0; i < names.length; i++) {
+    for (let j = 0; j < i; j++) {
+      const a = names[i];
+      const b = names[j];
+      const hit = byPair.get(pairKey(a, b));
+      pairs.push(
+        hit ? {
+          // Orient the pair the way the conflict states it, so `a` is the
+          // package making the demand rather than whichever came first in
+          // the argument list.
+          a: hit.packages[0] ?? a,
+          b: hit.packages[1] ?? b,
+          status: "conflict",
+          detail: hit.detail,
+          ...hit.requirement ? { requirement: hit.requirement } : {}
+        } : { a, b, status: "held" }
+      );
+    }
+  }
+  return pairs;
+}
+
+// src/usage/diff.ts
+init_esm_shims();
+function byName(surface) {
+  return new Map(surface.map((s) => [s.name, s]));
+}
+function looksRenamed(a, b) {
+  return a.kind === b.kind && a.signature !== null && a.signature === b.signature;
+}
+function diffSurface(oldSurface, newSurface) {
+  const oldByName = byName(oldSurface);
+  const newByName = byName(newSurface);
+  const removed = oldSurface.filter((s) => !newByName.has(s.name));
+  const added = newSurface.filter((s) => !oldByName.has(s.name));
+  const changed = [];
+  for (const oldSym of oldSurface) {
+    const newSym = newByName.get(oldSym.name);
+    if (newSym && oldSym.signature !== newSym.signature) {
+      changed.push({ name: oldSym.name, before: oldSym.signature, after: newSym.signature });
+    }
+  }
+  const renamed = [];
+  const takenAdded = /* @__PURE__ */ new Set();
+  const stillRemoved = [];
+  for (const r of removed) {
+    const match = added.find((a) => !takenAdded.has(a.name) && looksRenamed(r, a));
+    if (match) {
+      renamed.push({ from: r, to: match });
+      takenAdded.add(match.name);
+    } else {
+      stillRemoved.push(r);
+    }
+  }
+  return {
+    added: added.filter((a) => !takenAdded.has(a.name)),
+    removed: stillRemoved,
+    renamed,
+    changed
+  };
+}
+
+// src/usage/service.ts
+init_esm_shims();
+
+// src/usage/extract.ts
+init_esm_shims();
+import { posix } from "path";
+var CDN = "cdn.jsdelivr.net";
+function startWalk(opts) {
+  return {
+    ...opts,
+    expiresAt: opts.deadlineMs === void 0 ? Infinity : Date.now() + opts.deadlineMs
+  };
+}
+var compiler;
+function loadCompiler() {
+  compiler ??= import("typescript").then((m) => m.default ?? m).catch(() => null);
+  return compiler;
+}
+async function fetchFile(url, opts, ttlMs = CACHE_TTL.depsDev) {
+  if (Date.now() >= opts.expiresAt) return { text: null, unknown: true };
+  try {
+    const { data } = await httpRequest(url, {
+      host: CDN,
+      ttlMs,
+      accept: "text",
+      ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+      ...opts.retries !== void 0 ? { retries: opts.retries } : {}
+    });
+    return { text: typeof data === "string" ? data : null, unknown: false };
+  } catch (err) {
+    const missing = err instanceof HttpError && err.status === 404;
+    return { text: null, unknown: !missing };
+  }
+}
+async function fetchText(url, opts) {
+  return (await fetchFile(url, opts)).text;
+}
+var DTS_EXT = /\.d\.[cm]?ts$/;
+var JS_EXT = /\.(m|c)?js$/;
+function declarationFor(path) {
+  if (DTS_EXT.test(path)) return path;
+  const js = JS_EXT.exec(path);
+  return js ? path.replace(JS_EXT, `.d.${js[1] ?? ""}ts`) : null;
+}
+function relativeToRoot(path) {
+  return path.replace(/^\.?\//, "");
+}
+var EXPORT_CONDITIONS = ["types", "typings", "node", "import", "require", "default"];
+function typesFromExports(exports, depth = 0) {
+  if (depth > 4) return null;
+  if (typeof exports === "string") return declarationFor(exports);
+  if (!exports || typeof exports !== "object") return null;
+  if (Array.isArray(exports)) {
+    for (const alt of exports) {
+      const found = typesFromExports(alt, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  const map = exports;
+  if ("." in map) return typesFromExports(map["."], depth + 1);
+  if (Object.keys(map).some((k) => k.startsWith("."))) return null;
+  for (const condition of EXPORT_CONDITIONS) {
+    if (!(condition in map)) continue;
+    const found = typesFromExports(map[condition], depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+function typesEntries(pkgJson) {
+  const entries = [];
+  try {
+    const manifest = JSON.parse(pkgJson);
+    const declared = manifest.types ?? manifest.typings;
+    if (typeof declared === "string") entries.push(relativeToRoot(declared));
+    const fromExports = typesFromExports(manifest.exports);
+    if (fromExports) entries.push(relativeToRoot(fromExports));
+  } catch {
+  }
+  entries.push("index.d.ts");
+  return [...new Set(entries)];
+}
+function kindOf(ts, node) {
+  if (ts.isFunctionDeclaration(node)) return "function";
+  if (ts.isClassDeclaration(node)) return "class";
+  if (ts.isInterfaceDeclaration(node)) return "interface";
+  if (ts.isTypeAliasDeclaration(node)) return "type";
+  if (ts.isEnumDeclaration(node)) return "enum";
+  if (ts.isModuleDeclaration(node)) return "namespace";
+  if (ts.isVariableStatement(node)) return "variable";
+  return "unknown";
+}
+function normalize(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function signatureOf(ts, node, src) {
+  if (ts.isFunctionDeclaration(node)) {
+    const params = node.parameters.map((p) => normalize(p.getText(src))).join(", ");
+    const ret = node.type ? `: ${normalize(node.type.getText(src))}` : "";
+    return `(${params})${ret}`;
+  }
+  if (ts.isTypeAliasDeclaration(node)) return normalize(node.type.getText(src));
+  return null;
+}
+function hasExportModifier(ts, node) {
+  return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false);
+}
+function declarationsIn(ts, node, src) {
+  if (ts.isVariableStatement(node)) {
+    const out = [];
+    for (const decl of node.declarationList.declarations) {
+      if (ts.isIdentifier(decl.name)) {
+        out.push([
+          decl.name.text,
+          "variable",
+          decl.type ? normalize(decl.type.getText(src)) : null
+        ]);
+      }
+    }
+    return out;
+  }
+  const named = node;
+  if (named.name && ts.isIdentifier(named.name)) {
+    return [[named.name.text, kindOf(ts, node), signatureOf(ts, node, src)]];
+  }
+  return [];
+}
+function parseModule(source, ts) {
+  const src = ts.createSourceFile("surface.d.ts", source, ts.ScriptTarget.Latest, true);
+  const out = /* @__PURE__ */ new Map();
+  const stars = [];
+  const add = (name, kind, signature) => {
+    if (!out.has(name)) out.set(name, { name, kind, signature });
+  };
+  const local = /* @__PURE__ */ new Map();
+  const namespaces = /* @__PURE__ */ new Map();
+  for (const node of src.statements) {
+    for (const [name, kind, signature] of declarationsIn(ts, node, src)) {
+      if (!local.has(name)) local.set(name, { kind, signature });
+    }
+    if (ts.isModuleDeclaration(node) && ts.isIdentifier(node.name) && !namespaces.has(node.name.text)) {
+      namespaces.set(node.name.text, node);
+    }
+  }
+  const liftNamespace = (decl) => {
+    if (!decl.body || !ts.isModuleBlock(decl.body)) return;
+    for (const stmt of decl.body.statements) {
+      for (const [name, kind, signature] of declarationsIn(ts, stmt, src))
+        add(name, kind, signature);
+    }
+  };
+  for (const node of src.statements) {
+    if (ts.isExportDeclaration(node)) {
+      const clause = node.exportClause;
+      if (!clause) {
+        if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+          stars.push(node.moduleSpecifier.text);
+        }
+        continue;
+      }
+      if (ts.isNamespaceExport(clause)) {
+        add(clause.name.text, "namespace", null);
+        continue;
+      }
+      const reExport = node.moduleSpecifier !== void 0;
+      for (const el of clause.elements) {
+        const decl = reExport ? void 0 : local.get((el.propertyName ?? el.name).text);
+        const typeOnly = node.isTypeOnly || el.isTypeOnly;
+        add(el.name.text, decl?.kind ?? (typeOnly ? "type" : "unknown"), decl?.signature ?? null);
+      }
+      continue;
+    }
+    if (ts.isExportAssignment(node) && ts.isIdentifier(node.expression)) {
+      const target = node.expression.text;
+      const decl = local.get(target);
+      if (decl) add("default", decl.kind, decl.signature);
+      const ns = node.isExportEquals ? namespaces.get(target) : void 0;
+      if (ns) liftNamespace(ns);
+      continue;
+    }
+    if (!hasExportModifier(ts, node)) continue;
+    for (const [name, kind, signature] of declarationsIn(ts, node, src)) add(name, kind, signature);
+  }
+  return { symbols: [...out.values()].sort((a, b) => a.name.localeCompare(b.name)), stars };
+}
+function dtsCandidates(fromFile, specifier) {
+  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return [];
+  const path = posix.normalize(posix.join(posix.dirname(fromFile), specifier));
+  if (path.startsWith("..")) return [];
+  const paired = declarationFor(path);
+  if (paired) return [paired];
+  return [`${path}.d.ts`, `${path}/index.d.ts`];
+}
+var MAX_HOPS = 3;
+var MAX_FILES = 24;
+async function collectSurface(ts, root, entry, source, opts) {
+  const merged = /* @__PURE__ */ new Map();
+  const attempted = /* @__PURE__ */ new Set([entry]);
+  let budget = MAX_FILES;
+  let sound = true;
+  const absorb = (file, text) => {
+    const { symbols, stars } = parseModule(text, ts);
+    for (const s of symbols) if (!merged.has(s.name)) merged.set(s.name, s);
+    return stars.map((spec) => dtsCandidates(file, spec)).filter((c) => c.length > 0);
+  };
+  const fetchFirst = async (candidates) => {
+    for (const file of candidates) {
+      if (attempted.has(file) || budget <= 0) continue;
+      attempted.add(file);
+      budget--;
+      const { text, unknown } = await fetchFile(`${root}/${file}`, opts);
+      if (text !== null) return [file, text];
+      if (unknown) {
+        sound = false;
+        return null;
+      }
+    }
+    return null;
+  };
+  let frontier = absorb(entry, source);
+  for (let hop = 0; hop < MAX_HOPS && frontier.length > 0 && budget > 0; hop++) {
+    const fetched = await Promise.all(frontier.map(fetchFirst));
+    frontier = fetched.flatMap((hit) => hit ? absorb(hit[0], hit[1]) : []);
+  }
+  return { symbols: [...merged.values()].sort((a, b) => a.name.localeCompare(b.name)), sound };
+}
+async function surfaceFrom(ts, root, pkgJson, opts) {
+  for (const entry of typesEntries(pkgJson)) {
+    const dts = await fetchText(`${root}/${entry}`, opts);
+    if (!dts) continue;
+    const { symbols, sound } = await collectSurface(ts, root, entry, dts, opts);
+    if (sound && symbols.length > 0) return symbols;
+  }
+  return null;
+}
+function typesPackageName(name) {
+  return name.startsWith("@") ? `@types/${name.slice(1).replace("/", "__")}` : `@types/${name}`;
+}
+async function typesPackageSurface(ts, name, version, opts) {
+  const major = /^\d+/.exec(version)?.[0];
+  if (!major) return null;
+  const dt = typesPackageName(name);
+  const { text: pkgJson } = await fetchFile(
+    `https://${CDN}/npm/${dt}@${major}/package.json`,
+    opts,
+    CACHE_TTL.npmRegistry
+    // A floating range: don't hold it for a day.
+  );
+  if (!pkgJson) return null;
+  let resolved;
+  try {
+    resolved = JSON.parse(pkgJson).version;
+  } catch {
+    return null;
+  }
+  if (typeof resolved !== "string") return null;
+  return surfaceFrom(ts, `https://${CDN}/npm/${dt}@${resolved}`, pkgJson, opts);
+}
+async function extractSurface(name, version, opts = {}) {
+  const ts = await loadCompiler();
+  if (!ts) return null;
+  const walk = startWalk(opts);
+  const root = `https://${CDN}/npm/${name}@${version}`;
+  const pkgJson = await fetchText(`${root}/package.json`, walk);
+  if (!pkgJson) return null;
+  return await surfaceFrom(ts, root, pkgJson, walk) ?? typesPackageSurface(ts, name, version, walk);
+}
+
+// src/usage/service.ts
+var USAGE_EXTRACT_BUDGET_MS = 4e3;
+var READ_PATH_FETCH = { timeoutMs: 3e3, retries: 0, deadlineMs: 15e3 };
+var MAX_INFLIGHT = 64;
+var inFlight = /* @__PURE__ */ new Map();
+function extractOnce(db, name, version, fetchOpts) {
+  const key = `${name}@${version}`;
+  const existing = inFlight.get(key);
+  if (existing) return existing;
+  if (inFlight.size >= MAX_INFLIGHT) return Promise.resolve(null);
+  const task = extractSurface(name, version, fetchOpts).then(async (extracted) => {
+    if (extracted) await upsertSurface(db, name, version, extracted).catch(() => {
+    });
+    return extracted;
+  }).catch(() => null).finally(() => inFlight.delete(key));
+  inFlight.set(key, task);
+  return task;
+}
+async function getOrExtractSurface(db, name, version, opts = {}) {
+  const stored = await getStoredSurface(db, name, version);
+  if (stored) return stored;
+  if (opts.budgetMs === 0) return null;
+  const fetchOpts = opts.fetch ?? (opts.budgetMs === void 0 ? {} : READ_PATH_FETCH);
+  const task = extractOnce(db, name, version, fetchOpts);
+  return opts.budgetMs === void 0 ? task : withBudget(task, opts.budgetMs);
+}
+
+// src/search/recommend.ts
+init_esm_shims();
+import { and, cosineDistance, eq, inArray, isNotNull, lte, sql } from "drizzle-orm";
+var CONFIDENCE_ORDER = {
+  unproven: 0,
+  promising: 1,
+  emerging: 2,
+  proven: 3
+};
+var RRF_K = 60;
+function rankScore(row, relevance, lambda) {
+  const composite = computeComposite(row.healthScore ?? 0, row.qualityScore, lambda) / 100;
+  const confidence = CONFIDENCE_WEIGHT[row.confidence ?? "unproven"] ?? 0;
+  return RANKING.relevance * relevance + RANKING.composite * composite + RANKING.confidence * confidence;
+}
+async function recommend(db, opts, provider = createEmbeddingProvider()) {
+  const limit = Math.min(Math.max(opts.limit ?? 3, 1), 5);
+  let queryVec = null;
+  try {
+    queryVec = (await provider.embed([opts.need]))[0] ?? null;
+  } catch (err) {
+    queryVec = null;
+    const reason = err instanceof Error ? err.message : String(err);
+    logger.warn(`recommend: vector retrieval unavailable (${reason}); using lexical only.`);
+    opts.onDegraded?.(`vector retrieval unavailable: ${reason}`);
+  }
+  if (!queryVec) opts.onDegraded?.("vector retrieval unavailable");
+  const category = opts.category ?? inferCategory(opts.need);
+  const pool = Math.max(limit * 5, 25);
+  let fused = await hybridSearch(db, queryVec, provider.id, opts.need, opts.constraints, category, pool);
+  if (category && fused.length < limit) {
+    const broad = await hybridSearch(db, queryVec, provider.id, opts.need, opts.constraints, null, pool);
+    const seen = new Set(fused.map((f) => f.row.name));
+    fused = fused.concat(broad.filter((f) => !seen.has(f.row.name)));
+  }
+  if (fused.length === 0) return [];
+  const lambda = loadWeights().composite.lambda;
+  const maxRrf = Math.max(...fused.map((f) => f.rrf));
+  const ranked = fused.map((f) => ({
+    row: f.row,
+    score: rankScore(f.row, maxRrf > 0 ? f.rrf / maxRrf : 0, lambda)
+  })).sort((a, b) => b.score - a.score).slice(0, limit);
+  return ranked.map(({ row }) => toCandidate(row));
+}
+async function hybridSearch(db, queryVec, providerId, need, constraints, category, pool) {
+  const [vectorRows, lexicalRows] = await Promise.all([
+    queryVec ? runVectorQuery(db, queryVec, providerId, constraints, category, pool) : [],
+    runLexicalQuery(db, need, constraints, category, pool)
+  ]);
+  return rrfFuse([vectorRows, lexicalRows]);
+}
+function rrfFuse(lists, k = RRF_K) {
+  const fused = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    list.forEach((row, idx) => {
+      const contribution = 1 / (k + idx + 1);
+      const prev = fused.get(row.name);
+      if (prev) prev.rrf += contribution;
+      else fused.set(row.name, { row, rrf: contribution });
+    });
+  }
+  return [...fused.values()].sort((a, b) => b.rrf - a.rrf);
+}
+var ROW_COLUMNS = {
+  name: packages.name,
+  category: packages.category,
+  healthScore: packages.healthScore,
+  qualityScore: packages.qualityScore,
+  confidence: packages.confidence,
+  latestVersion: packages.latestVersion,
+  weeklyDownloads: packages.weeklyDownloads,
+  lastReleaseAt: packages.lastReleaseAt,
+  repoUrl: packages.repoUrl,
+  deprecated: packages.deprecated,
+  archived: packages.archived,
+  // The count, not the array: an agent shortlisting five packages needs to know
+  // that one carries advisories, and `evaluate` is where it reads which. Pulling
+  // the jsonb payload for every candidate would cost tokens on every call for
+  // detail the next call already serves.
+  advisories: sql`coalesce(jsonb_array_length(${packages.advisories}), 0)`
+};
+function buildConditions(constraints, category) {
+  const conditions = [];
+  if (category) conditions.push(eq(packages.category, category));
+  if (constraints?.license) conditions.push(eq(packages.license, constraints.license));
+  if (constraints?.maxBundleKb !== void 0) {
+    conditions.push(lte(packages.bundleMinGzipKb, constraints.maxBundleKb));
+  }
+  if (constraints?.minConfidence) {
+    const allowed = ["proven", "emerging", "promising", "unproven"].filter(
+      (c) => CONFIDENCE_ORDER[c] >= CONFIDENCE_ORDER[constraints.minConfidence]
+    );
+    conditions.push(inArray(packages.confidence, allowed));
+  }
+  return conditions;
+}
+async function runVectorQuery(db, queryVec, providerId, constraints, category, pool) {
+  const distance = cosineDistance(packages.embedding, queryVec);
+  const conditions = [
+    isNotNull(packages.embedding),
+    eq(packages.embeddingProvider, providerId),
+    ...buildConditions(constraints, category)
+  ];
+  return db.select(ROW_COLUMNS).from(packages).where(and(...conditions)).orderBy(distance).limit(pool);
+}
+async function runLexicalQuery(db, need, constraints, category, pool) {
+  const tsquery = sql`websearch_to_tsquery('english', ${need})`;
+  const rank = sql`ts_rank(${packages.searchVector}, ${tsquery})`;
+  const conditions = [sql`${packages.searchVector} @@ ${tsquery}`, ...buildConditions(constraints, category)];
+  return db.select(ROW_COLUMNS).from(packages).where(and(...conditions)).orderBy(sql`${rank} desc`).limit(pool);
+}
+function toCandidate(row) {
+  return {
+    name: row.name,
+    category: row.category,
+    healthScore: row.healthScore ?? 0,
+    qualityScore: row.qualityScore,
+    confidence: row.confidence ?? "unproven",
+    why: buildWhy(row),
+    latestVersion: row.latestVersion,
+    weeklyDownloads: row.weeklyDownloads,
+    lastReleaseAt: row.lastReleaseAt ? row.lastReleaseAt.toISOString() : null,
+    repoUrl: row.repoUrl,
+    deprecated: row.deprecated ?? false,
+    archived: row.archived ?? false,
+    advisories: Number(row.advisories ?? 0)
+  };
+}
+function buildWhy(row) {
+  const warnings = [];
+  if (row.deprecated) warnings.push("DEPRECATED");
+  if (row.archived) warnings.push("repo archived");
+  if (row.advisories) {
+    warnings.push(`${row.advisories} advisor${row.advisories === 1 ? "y" : "ies"}`);
+  }
+  const parts = [];
+  if (row.confidence) parts.push(row.confidence);
+  if (row.weeklyDownloads) parts.push(`${formatDownloads(row.weeklyDownloads)} weekly downloads`);
+  if (row.healthScore !== null) parts.push(`health ${row.healthScore}`);
+  const rationale = parts.join(", ") || "tracked package";
+  return warnings.length ? `${warnings.join(" + ")} \u2014 ${rationale}` : rationale;
+}
+function formatDownloads(n) {
+  if (n >= 1e6) return `${Math.round(n / 1e5) / 10}M`;
+  if (n >= 1e3) return `${Math.round(n / 1e3)}k`;
+  return String(n);
+}
+
+// src/db/selectionPolicy.ts
+init_esm_shims();
+import { and as and2, desc, eq as eq2, gte, inArray as inArray2, sql as sql2 } from "drizzle-orm";
+
+// src/policy/types.ts
+init_esm_shims();
+var DEFAULT_SELECTION_POLICY = {
+  mode: "enforce",
+  allow: [],
+  deny: [],
+  minConfidence: null,
+  licenses: null,
+  blockDeprecated: false,
+  blockArchived: false,
+  maxAdvisorySeverity: null,
+  minWeeklyDownloads: null,
+  maxStaleMonths: null,
+  maxBundleKb: null,
+  minPackageAgeDays: null
+};
+
+// src/db/selectionPolicy.ts
+async function getSelectionPolicy(db, ownerId) {
+  if (!ownerId) return DEFAULT_SELECTION_POLICY;
+  const [row] = await db.select({ policy: selectionPolicies.policy }).from(selectionPolicies).where(eq2(selectionPolicies.ownerId, ownerId)).limit(1);
+  if (!row) return DEFAULT_SELECTION_POLICY;
+  const stored = { ...DEFAULT_SELECTION_POLICY, ...row.policy };
+  const allow = stored.allow.map(
+    (a) => typeof a === "string" ? { name: a } : a
+  );
+  return { ...stored, allow };
+}
+async function getEnforcedPolicy(db, ownerId) {
+  return withoutExpired(await getSelectionPolicy(db, ownerId), /* @__PURE__ */ new Date());
+}
+async function setSelectionPolicy(db, ownerId, policy, actor) {
+  const previous = await getSelectionPolicy(db, ownerId);
+  await db.transaction(async (tx) => {
+    await tx.insert(selectionPolicies).values({ ownerId, policy, updatedAt: /* @__PURE__ */ new Date() }).onConflictDoUpdate({
+      target: selectionPolicies.ownerId,
+      set: { policy, updatedAt: /* @__PURE__ */ new Date() }
+    });
+    await tx.insert(selectionPolicyChanges).values({ ownerId, actor, before: previous, after: policy });
+  });
+  return previous;
+}
+async function listPolicyChanges(db, ownerId, limit = 20) {
+  const rows = await db.select().from(selectionPolicyChanges).where(eq2(selectionPolicyChanges.ownerId, ownerId)).orderBy(desc(selectionPolicyChanges.createdAt), desc(selectionPolicyChanges.id)).limit(limit);
+  return rows.map((row) => ({
+    actor: row.actor,
+    at: row.createdAt,
+    changes: diffPolicies(row.before, row.after),
+    before: row.before,
+    after: row.after
+  }));
+}
+async function recordDecisions(db, ownerId, tool, exclusions, action) {
+  if (!ownerId || exclusions.length === 0) return;
+  try {
+    await db.insert(policyDecisions).values(
+      exclusions.map((e) => ({ ownerId, packageName: e.name, rule: e.rule, action, tool }))
+    );
+  } catch {
+  }
+}
+async function summarizeDecisions(db, ownerId, days) {
+  const count = sql2`count(*)::int`;
+  return db.select({
+    packageName: policyDecisions.packageName,
+    rule: policyDecisions.rule,
+    action: policyDecisions.action,
+    count,
+    lastDay: sql2`to_char(max(${policyDecisions.createdAt}) at time zone 'UTC', 'YYYY-MM-DD')`
+  }).from(policyDecisions).where(
+    and2(
+      eq2(policyDecisions.ownerId, ownerId),
+      // `::int` for the same reason usage.ts's windowStart casts: an uncast JS
+      // number leaves Postgres to guess the operand type.
+      gte(policyDecisions.createdAt, sql2`now() - make_interval(days => ${days}::int)`)
+    )
+  ).groupBy(policyDecisions.packageName, policyDecisions.rule, policyDecisions.action).orderBy(desc(count)).limit(100);
+}
+function daysSince(date) {
+  if (!date) return null;
+  return Math.max(0, Math.floor((Date.now() - date.getTime()) / (1e3 * 60 * 60 * 24)));
+}
+function monthsSince(date) {
+  if (!date) return null;
+  const ms = Date.now() - date.getTime();
+  if (ms < 0) return 0;
+  return Math.floor(ms / (1e3 * 60 * 60 * 24 * 30.44));
+}
+async function loadPolicyFacts(db, names, ecosystem = DEFAULT_ECOSYSTEM) {
+  const out = /* @__PURE__ */ new Map();
+  if (names.length === 0) return out;
+  const rows = await db.select({
+    name: packages.name,
+    license: packages.license,
+    deprecated: packages.deprecated,
+    archived: packages.archived,
+    advisories: packages.advisories,
+    weeklyDownloads: packages.weeklyDownloads,
+    lastReleaseAt: packages.lastReleaseAt,
+    bundleMinGzipKb: packages.bundleMinGzipKb,
+    firstPublishedAt: packages.firstPublishedAt
+  }).from(packages).where(and2(inArray2(packages.name, names), eq2(packages.ecosystem, ecosystem)));
+  for (const row of rows) {
+    out.set(row.name, {
+      license: row.license,
+      deprecated: row.deprecated,
+      archived: row.archived,
+      advisories: row.advisories,
+      weeklyDownloads: row.weeklyDownloads,
+      // Resolved here, not in `check`: the rules stay a pure function with no
+      // clock, which is what lets every one of them be tested exhaustively.
+      monthsSinceRelease: monthsSince(row.lastReleaseAt),
+      bundleKb: row.bundleMinGzipKb,
+      daysSincePublished: daysSince(row.firstPublishedAt)
+    });
+  }
+  return out;
+}
+
+// src/security/typosquat.ts
+init_esm_shims();
+
+// src/data/popular-packages.json
+var popular_packages_default = [
+  "react",
+  "react-dom",
+  "react-router",
+  "react-router-dom",
+  "next",
+  "vue",
+  "vue-router",
+  "pinia",
+  "vuex",
+  "svelte",
+  "solid-js",
+  "preact",
+  "angular",
+  "@angular/core",
+  "jquery",
+  "lodash",
+  "underscore",
+  "ramda",
+  "immer",
+  "rxjs",
+  "express",
+  "koa",
+  "fastify",
+  "@nestjs/core",
+  "hapi",
+  "connect",
+  "body-parser",
+  "cookie-parser",
+  "cors",
+  "helmet",
+  "morgan",
+  "compression",
+  "express-session",
+  "express-rate-limit",
+  "multer",
+  "passport",
+  "jsonwebtoken",
+  "bcrypt",
+  "bcryptjs",
+  "axios",
+  "node-fetch",
+  "got",
+  "undici",
+  "superagent",
+  "request",
+  "cheerio",
+  "puppeteer",
+  "playwright",
+  "cypress",
+  "jsdom",
+  "ws",
+  "socket.io",
+  "socket.io-client",
+  "graphql",
+  "@apollo/client",
+  "apollo-server",
+  "dataloader",
+  "mongoose",
+  "mongodb",
+  "pg",
+  "mysql2",
+  "sequelize",
+  "prisma",
+  "knex",
+  "drizzle-orm",
+  "typeorm",
+  "redis",
+  "ioredis",
+  "sqlite3",
+  "better-sqlite3",
+  "typescript",
+  "eslint",
+  "prettier",
+  "tslint",
+  "webpack",
+  "vite",
+  "rollup",
+  "esbuild",
+  "parcel",
+  "@babel/core",
+  "babel-core",
+  "babel-loader",
+  "ts-node",
+  "tsx",
+  "tsup",
+  "nodemon",
+  "concurrently",
+  "npm-run-all",
+  "jest",
+  "vitest",
+  "mocha",
+  "chai",
+  "sinon",
+  "ava",
+  "tape",
+  "supertest",
+  "@testing-library/react",
+  "enzyme",
+  "chalk",
+  "colors",
+  "kleur",
+  "picocolors",
+  "ansi-colors",
+  "commander",
+  "yargs",
+  "meow",
+  "minimist",
+  "inquirer",
+  "prompts",
+  "ora",
+  "boxen",
+  "figlet",
+  "cli-progress",
+  "debug",
+  "dotenv",
+  "cross-env",
+  "rimraf",
+  "glob",
+  "fast-glob",
+  "chokidar",
+  "fs-extra",
+  "execa",
+  "cross-spawn",
+  "shelljs",
+  "which",
+  "semver",
+  "uuid",
+  "nanoid",
+  "ulid",
+  "moment",
+  "dayjs",
+  "date-fns",
+  "luxon",
+  "zod",
+  "yup",
+  "joi",
+  "ajv",
+  "validator",
+  "class-validator",
+  "winston",
+  "pino",
+  "bunyan",
+  "nodemailer",
+  "node-cron",
+  "bull",
+  "bullmq",
+  "kafkajs",
+  "amqplib",
+  "sharp",
+  "jimp",
+  "archiver",
+  "tar",
+  "adm-zip",
+  "qs",
+  "query-string",
+  "form-data",
+  "mime-types",
+  "http-errors",
+  "classnames",
+  "clsx",
+  "styled-components",
+  "@emotion/react",
+  "tailwindcss",
+  "postcss",
+  "autoprefixer",
+  "sass",
+  "less",
+  "framer-motion",
+  "three",
+  "d3",
+  "chart.js",
+  "recharts",
+  "gsap",
+  "swiper",
+  "leaflet",
+  "mapbox-gl",
+  "formik",
+  "react-hook-form",
+  "redux",
+  "@reduxjs/toolkit",
+  "zustand",
+  "jotai",
+  "mobx",
+  "bootstrap",
+  "@popperjs/core",
+  "aws-sdk",
+  "@aws-sdk/client-s3",
+  "firebase",
+  "firebase-admin",
+  "stripe",
+  "twilio",
+  "openai",
+  "@anthropic-ai/sdk",
+  "googleapis",
+  "bignumber.js",
+  "decimal.js",
+  "mathjs",
+  "slugify",
+  "faker",
+  "@faker-js/faker",
+  "puppeteer-core"
+];
+
+// src/security/typosquat.ts
+var POPULAR_BASELINE = popular_packages_default;
+function typosquatCorpus(trackedTopNames) {
+  return [.../* @__PURE__ */ new Set([...POPULAR_BASELINE, ...trackedTopNames])];
+}
+function bareName(name) {
+  const slash = name.indexOf("/");
+  return (slash >= 0 ? name.slice(slash + 1) : name).toLowerCase();
+}
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prevPrev = new Array(n + 1).fill(0);
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const cur = new Array(n + 1).fill(0);
+    cur[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let val = Math.min(
+        (prev[j] ?? 0) + 1,
+        (cur[j - 1] ?? 0) + 1,
+        (prev[j - 1] ?? 0) + cost
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        val = Math.min(val, (prevPrev[j - 2] ?? 0) + 1);
+      }
+      cur[j] = val;
+    }
+    prevPrev = prev;
+    prev = cur;
+  }
+  return prev[n] ?? 0;
+}
+function detectTyposquat(name, popular, maxDistance = 2) {
+  const target = bareName(name);
+  if (target.length < 4) return null;
+  if (popular.some((p) => p.toLowerCase() === name.toLowerCase())) return null;
+  let best = null;
+  for (const p of popular) {
+    const cand = bareName(p);
+    if (cand === target) continue;
+    if (Math.abs(cand.length - target.length) > maxDistance) continue;
+    const dist = editDistance(target, cand);
+    if (dist >= 1 && dist <= maxDistance && (!best || dist < best.distance)) {
+      best = { target: p, distance: dist };
+      if (dist === 1) break;
+    }
+  }
+  return best;
+}
+
+// src/mcp/handlers.ts
+var SEVERITY_RANK = {
+  critical: 4,
+  high: 3,
+  moderate: 2,
+  low: 1,
+  info: 0
+};
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function isStale(dataAsOf) {
+  if (!dataAsOf) return true;
+  return Date.now() - dataAsOf.getTime() > STALENESS_DAYS * DAY_MS;
+}
+function refreshStale(out) {
+  out.stale = isStale(out.dataAsOf ? new Date(out.dataAsOf) : null) || void 0;
+  return out;
+}
+function withinDays(date, days) {
+  return date ? Date.now() - date.getTime() <= days * DAY_MS : false;
+}
+function topAdvisories(advisories, max = 5) {
+  if (!advisories) return null;
+  return [...advisories].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]).slice(0, max);
+}
+function rowToEvaluate(row, learned) {
+  const breakdown = row.scoreBreakdown ?? {
+    maintenance: 0,
+    adoption: 0,
+    reliability: 0,
+    efficiency: null,
+    quality: null
+  };
+  return {
+    dataAsOf: (row.dataAsOf ?? /* @__PURE__ */ new Date()).toISOString(),
+    stale: isStale(row.dataAsOf) || void 0,
+    name: row.name,
+    category: row.category,
+    healthScore: row.healthScore ?? 0,
+    qualityScore: row.qualityScore ?? null,
+    confidence: row.confidence ?? "unproven",
+    scoreBreakdown: breakdown,
+    latestVersion: row.latestVersion,
+    lastReleaseAt: row.lastReleaseAt ? row.lastReleaseAt.toISOString() : null,
+    weeklyDownloads: row.weeklyDownloads,
+    downloadGrowth90d: row.downloadGrowth90d,
+    scorecard: row.scorecard,
+    bundleMinGzipKb: row.bundleMinGzipKb,
+    deprecated: row.deprecated,
+    archived: row.archived,
+    advisories: topAdvisories(row.advisories),
+    // The SAME call `verify` and `audit` make. A health score is a quality
+    // measure and must never be read as a safety clearance, so the verdict
+    // travels beside it — and because all three surfaces derive it here, they
+    // can no longer disagree about the same package.
+    verdict: assessVerdict({
+      exists: true,
+      advisories: row.advisories ?? null,
+      deprecated: row.deprecated,
+      archived: row.archived,
+      lowTrust: (row.weeklyDownloads ?? 0) < 1e3,
+      subjectVersion: row.latestVersion
+    }),
+    summary: row.summary ? truncateSentences(row.summary, 3) : null,
+    usageGuide: row.usageGuide ?? null,
+    repoUrl: row.repoUrl,
+    replacedBy: lookupSuccessor(row.name, learned)
+  };
+}
+async function latestDataAsOf(db) {
+  const [row] = await db.select({ m: sql3`max(${packages.dataAsOf})` }).from(packages);
+  return new Date(row?.m ?? Date.now()).toISOString();
+}
+function cacheKey(parts) {
+  return createHash("sha1").update(JSON.stringify(parts)).digest("hex").slice(0, 24);
+}
+async function handleRecommend(db, input, ownerId = null) {
+  const base = await cached(
+    "rec",
+    cacheKey([input.need, input.category ?? null, input.constraints ?? null]),
+    async () => {
+      let degraded = null;
+      const candidates = await recommend(db, {
+        need: input.need,
+        category: input.category,
+        constraints: input.constraints,
+        limit: 5,
+        onDegraded: (reason) => {
+          degraded = reason;
+        }
+      });
+      return { dataAsOf: await latestDataAsOf(db), candidates, degraded };
+    },
+    {
+      // Don't cache empty results — the index may still be populating. Nor
+      // degraded ones: a lexical-only ranking written into the shared cache
+      // outlives the outage that produced it and gets served back long after
+      // the vector leg recovers.
+      skipCache: (r) => r.candidates.length === 0 || r.degraded !== null
+    }
+  );
+  const policy = await getEnforcedPolicy(db, ownerId);
+  if (!hasRules(policy)) return base;
+  const facts = await loadPolicyFacts(
+    db,
+    base.candidates.map((c) => c.name)
+  );
+  const { allowed, excluded, warned } = applyPolicy(policy, base.candidates, facts);
+  void (policy.mode === "warn" ? recordDecisions(db, ownerId, "recommend", warned, "warned") : recordDecisions(db, ownerId, "recommend", excluded, "blocked"));
+  return policy.mode === "warn" ? { ...base, candidates: allowed, policyWarnings: warned } : { ...base, candidates: allowed, excluded };
+}
+async function handlePolicy(db, ownerId) {
+  if (!ownerId) {
+    return {
+      enforced: false,
+      rules: [],
+      note: "No lurq account on this connection, so no policy applies. Connect with `lurq setup`."
+    };
+  }
+  const rules = describeRules(await getEnforcedPolicy(db, ownerId));
+  return { enforced: rules.length > 0, rules };
+}
+async function handleEvaluate(db, input, ownerId = null) {
+  const out = await cached(
+    "eval",
+    cacheKey([input.package]),
+    async () => {
+      const { row, existsOnNpm } = await getOrFetchPackage(db, input.package, {
+        blockMs: FIRST_TOUCH_BUDGET_MS,
+        requestedByOwnerId: ownerId
+      });
+      if (!row) {
+        return {
+          tracked: false,
+          suggestion: existsOnNpm ? `\u{1F389} Congrats, you're the first to add "${input.package}" to lurq's registry! It's being fetched and scored now; retry in a few seconds for the full evidence read.` : `"${input.package}" was not found on the npm registry. Check the package name.`
+        };
+      }
+      const learned = row.deprecated || row.archived ? await loadLearnedSuccessors(db) : void 0;
+      const evaluated2 = rowToEvaluate(row, learned);
+      const verification = await getLatestVerificationByName(db, row.name);
+      return verification ? { ...evaluated2, buildVerified: toBuildVerified(verification) } : evaluated2;
+    },
+    // Don't cache "not found / not scored yet" — it may resolve on a later fetch.
+    { skipCache: (r) => "tracked" in r }
+  );
+  if ("tracked" in out) return out;
+  const evaluated = refreshStale(out);
+  const policy = await getEnforcedPolicy(db, ownerId);
+  if (!hasRules(policy)) return evaluated;
+  const facts = await loadPolicyFacts(db, [evaluated.name]);
+  const exclusion = check(
+    policy,
+    { name: evaluated.name, confidence: evaluated.confidence },
+    facts.get(evaluated.name)
+  );
+  if (!exclusion) return { ...evaluated, policy: { allowed: true } };
+  void recordDecisions(
+    db,
+    ownerId,
+    "evaluate",
+    [exclusion],
+    policy.mode === "warn" ? "warned" : "blocked"
+  );
+  return {
+    ...evaluated,
+    policy: policy.mode === "warn" ? { allowed: true, warning: exclusion } : { allowed: false, ...exclusion }
+  };
+}
+function comparisonNote(notFound, pending) {
+  return [
+    notFound.length ? `Not found on the npm registry: ${notFound.join(", ")}. Check the name(s) before installing \u2014 these do not exist.` : null,
+    pending.length ? `\u{1F389} You're the first to add ${pending.join(", ")} to lurq's registry! They're being scored now; retry shortly for the full comparison.` : null
+  ].filter(Boolean).join(" ");
+}
+async function handleCompare(db, input, ownerId = null) {
+  const out = await cached(
+    "cmp",
+    cacheKey(input.packages),
+    async () => {
+      const results = await Promise.all(
+        input.packages.map((name) => getOrFetchPackage(db, name, { requestedByOwnerId: ownerId }))
+      );
+      const rows = results.map((r) => r.row).filter((row) => row !== null).map((row) => rowToEvaluate(row)).sort((a, b) => b.healthScore - a.healthScore);
+      const missing = [];
+      const notFound = [];
+      const pending = [];
+      input.packages.forEach((name, i) => {
+        const result = results[i];
+        if (result.row) return;
+        missing.push(name);
+        (result.existsOnNpm ? pending : notFound).push(name);
+      });
+      return {
+        dataAsOf: await latestDataAsOf(db),
+        rows,
+        // `missing` stays the union, in the caller's own order, so a client
+        // pinned to an older lurq keeps printing its "not found" line.
+        ...missing.length ? { missing } : {},
+        ...notFound.length ? { notFound } : {},
+        ...pending.length ? { pending } : {},
+        ...missing.length ? { note: comparisonNote(notFound, pending) } : {}
+      };
+    },
+    // Don't cache a miss: a pending ingest lands within seconds, and a name that
+    // is not on npm today may be published tomorrow.
+    { skipCache: (r) => Boolean(r.missing?.length) }
+  );
+  out.rows = out.rows.map(refreshStale);
+  return out;
+}
+function toBuildVerified(v) {
+  return {
+    version: v.version,
+    installed: v.installed,
+    loaded: v.imported,
+    driver: v.driver,
+    ranAt: v.ranAt ? v.ranAt.toISOString() : ""
+  };
+}
+async function handleCompat(db, input) {
+  return checkCompat(db, input.packages, {
+    versions: input.versions,
+    node: input.node
+  });
+}
+async function handleVerify(db, input, ownerId = null) {
+  const name = input.package;
+  const exists = await npmPackageExists(name);
+  if (!exists) {
+    const typo2 = detectTyposquat(
+      name,
+      typosquatCorpus(await getTopPackageNames(db).catch(() => []))
+    );
+    return {
+      exists: false,
+      tracked: false,
+      deprecated: false,
+      archived: false,
+      latestVersion: null,
+      weeklyDownloads: null,
+      riskFlags: typo2 ? ["not-found-on-registry", `possible-typosquat-of:${typo2.target}`] : ["not-found-on-registry"],
+      risk: "high",
+      // `invalid`, not `high`: this is a statement about the INPUT. Calling it
+      // a risk level invites the reader to weigh it against a benefit, and
+      // there is no package here to weigh.
+      verdict: assessVerdict({
+        exists: false,
+        advisories: null,
+        typosquatOf: typo2?.target ?? null
+      }),
+      typosquatOf: typo2?.target ?? null,
+      confidence: null,
+      advisoryCount: null
+    };
+  }
+  const [registry, { row, wasTracked }, popular] = await Promise.all([
+    fetchNpmRegistry(name).catch(() => null),
+    // Block-on-first-touch (§4A): verify is single-package, so await the ingest
+    // for a real confidence/tracked read on the first call.
+    getOrFetchPackage(db, name, { blockMs: FIRST_TOUCH_BUDGET_MS, requestedByOwnerId: ownerId }),
+    getTopPackageNames(db).catch(() => [])
+  ]);
+  const weeklyDownloads = row?.weeklyDownloads ?? await fetchWeeklyDownloads(name).catch(() => null);
+  const advisories = row?.advisories ?? null;
+  const advisoryCount = advisories?.length ?? null;
+  const deprecated = Boolean(row?.deprecated || registry?.deprecated);
+  const archived = Boolean(row?.archived);
+  const brandNew = withinDays(registry?.firstPublishedAt ?? null, 7);
+  const lowTrust = weeklyDownloads === null || weeklyDownloads < 1e3;
+  const installScripts = registry?.hasInstallScripts ?? false;
+  const typo = detectTyposquat(name, typosquatCorpus(popular));
+  const riskFlags = [];
+  if (typo) riskFlags.push(`possible-typosquat-of:${typo.target}`);
+  if (weeklyDownloads === null || weeklyDownloads === 0) riskFlags.push("zero-downloads");
+  else if (weeklyDownloads < 1e3) riskFlags.push("low-downloads");
+  if (brandNew) riskFlags.push("published-within-7-days");
+  if (registry?.maintainersCount === 1) riskFlags.push("single-maintainer");
+  if (installScripts) riskFlags.push("runs-install-scripts");
+  if (advisoryCount === null) riskFlags.push("advisories-not-yet-checked");
+  else if (advisoryCount > 0) riskFlags.push("has-known-advisory");
+  if (deprecated) riskFlags.push("deprecated");
+  if (archived) riskFlags.push("archived");
+  const verdict = assessVerdict({
+    exists: true,
+    advisories,
+    typosquatOf: typo?.target ?? null,
+    installScripts,
+    brandNew,
+    lowTrust,
+    deprecated,
+    archived,
+    singleMaintainer: registry?.maintainersCount === 1,
+    subjectVersion: registry?.latestVersion ?? row?.latestVersion ?? null
+  });
+  return {
+    exists: true,
+    tracked: wasTracked,
+    deprecated,
+    archived,
+    latestVersion: registry?.latestVersion ?? row?.latestVersion ?? null,
+    weeklyDownloads,
+    riskFlags,
+    // `invalid` cannot occur here (exists is true), so the cast is total.
+    risk: verdict.level,
+    verdict,
+    typosquatOf: typo?.target ?? null,
+    confidence: row?.confidence ?? null,
+    advisoryCount
+  };
+}
+async function resolveVersion(db, name, requested) {
+  if (requested) {
+    const exists = await npmVersionExists(name, requested);
+    return exists === false ? { version: null, unpublished: true } : { version: requested };
+  }
+  const row = await getPackageByName(db, name);
+  if (row?.latestVersion) return { version: row.latestVersion };
+  const reg = await fetchNpmRegistry(name).catch(() => null);
+  return { version: reg?.latestVersion ?? null };
+}
+var USAGE_PAGE_SIZE = 80;
+function pageSurface(surface, input) {
+  const q = input.query?.trim().toLowerCase();
+  const matched = q ? surface.filter((s) => s.name.toLowerCase().includes(q)) : surface;
+  const offset = Math.max(0, Math.floor(input.offset ?? 0));
+  const symbols = matched.slice(offset, offset + USAGE_PAGE_SIZE);
+  const total = matched.length;
+  const what = q ? `symbols matching "${input.query}"` : "exported symbols";
+  if (q && total === 0) {
+    return {
+      symbols,
+      total,
+      note: `No exported symbol name contains "${input.query}" (${surface.length} in total). Try a shorter fragment, or omit query to page through all of them.`
+    };
+  }
+  if (offset >= total && total > 0) {
+    return { symbols, total, note: `offset ${offset} is past the last of ${total} ${what}.` };
+  }
+  const end = offset + symbols.length;
+  if (offset === 0 && end === total) return { symbols, total };
+  return {
+    symbols,
+    total,
+    note: `Showing ${offset + 1}\u2013${end} of ${total} ${what}, sorted by name. ` + (end < total ? `Pass offset: ${end} for the next page, or query with part of a name to jump to it.` : "This is the last page.")
+  };
+}
+function isShallowSurface(surface) {
+  const main = surface.find((s) => s.name === "default");
+  const rest = surface.filter((s) => s !== main);
+  return main?.kind === "variable" && rest.length > 0 && rest.length <= 3 && rest.every((s) => s.kind === "interface" || s.kind === "type" || s.kind === "namespace");
+}
+async function handleUsage(db, input) {
+  const resolved = await resolveVersion(db, input.package, input.version);
+  const version = resolved.version;
+  if (!version) {
+    return {
+      package: input.package,
+      version: null,
+      surface: null,
+      available: false,
+      engines: null,
+      note: resolved.unpublished ? `"${input.package}" has no published version ${input.version}. That release does not exist on the npm registry \u2014 check the version before writing code against it.` : `Could not resolve a version for "${input.package}" on npm.`,
+      ...resolved.unpublished ? { unpublishedVersion: input.version } : {}
+    };
+  }
+  const deadline = Date.now() + USAGE_EXTRACT_BUDGET_MS;
+  const [surface, compat] = await Promise.all([
+    getOrExtractSurface(db, input.package, version, {
+      budgetMs: USAGE_EXTRACT_BUDGET_MS
+    }),
+    fetchNpmCompatAtVersion(input.package, version).catch(() => null)
+  ]);
+  const page = surface ? pageSurface(surface, input) : null;
+  const shallow = surface !== null && isShallowSurface(surface);
+  const types = typesPackageName(input.package);
+  const out = {
+    package: input.package,
+    version,
+    surface: page?.symbols ?? null,
+    available: surface !== null,
+    engines: compat?.engines ?? null,
+    ...page ? { totalSymbols: page.total } : {},
+    ...shallow ? { shallow: true } : {},
+    note: !surface ? (
+      // The README is not in this response, so "fall back to the README"
+      // left the agent with nothing to act on. Name the two things it can do.
+      `No type-derived API surface for ${input.package}@${version}: it ships no .d.ts and ${types} has no matching major, or extraction is still running (retry in a few seconds). For the names it exports at runtime call resolve_surface; for usage, read https://www.npmjs.com/package/${input.package}/v/${version}.`
+    ) : shallow ? `Shallow surface: ${input.package} exports one value typed by ${surface.filter((s) => s.name !== "default").map((s) => s.name).join(", ")}, so its methods are that interface's members and are NOT listed here. Read them in its type declarations (${types} if the package bundles none), or call resolve_surface for the names it exports at runtime.` : page?.note
+  };
+  if (input.knownVersion && input.knownVersion !== version && surface) {
+    const known = await getOrExtractSurface(db, input.package, input.knownVersion, {
+      budgetMs: Math.max(0, deadline - Date.now())
+    });
+    if (known) out.delta = { ...diffSurface(known, surface), fromVersion: input.knownVersion };
+    else {
+      const knownExists = await npmVersionExists(input.package, input.knownVersion);
+      out.deltaNote = knownExists === false ? `No delta: "${input.package}" has no published version ${input.knownVersion}. That release does not exist on the npm registry.` : `No delta: no API surface extracted for ${input.package}@${input.knownVersion} yet. Retry shortly, or compare against a version that has been indexed.`;
+    }
+  }
+  return out;
+}
+async function handleReportOutcome(db, input, ownerId = null) {
+  await recordOutcome(db, {
+    ownerId,
+    packageName: input.package,
+    accepted: input.accepted,
+    buildSignal: input.buildSignal ?? null,
+    need: input.need ?? null
+  });
+  return { recorded: true };
+}
+
+export {
+  checkCompat,
+  recommend,
+  getSelectionPolicy,
+  getEnforcedPolicy,
+  setSelectionPolicy,
+  listPolicyChanges,
+  summarizeDecisions,
+  daysSince,
+  rowToEvaluate,
+  latestDataAsOf,
+  handleRecommend,
+  handlePolicy,
+  handleEvaluate,
+  handleCompare,
+  handleCompat,
+  handleVerify,
+  USAGE_PAGE_SIZE,
+  handleUsage,
+  handleReportOutcome
+};