lurqrun 0.0.4 → 0.0.6

package/dist/index.js

@@ -24,7 +24,7 @@ function isCategory(value) {
 function isFrontendCategory(category) {
   return category != null && FRONTEND_CATEGORIES.includes(category);
 }
-var CATEGORIES, FRONTEND_CATEGORIES;
+var CATEGORIES, FRONTEND_CATEGORIES, PROVENANCE_RANK;
 var init_types = __esm({
   "src/core/types.ts"() {
     "use strict";
@@ -66,6 +66,12 @@ var init_types = __esm({
       "date-time",
       "utility"
     ];
+    PROVENANCE_RANK = {
+      declared: 0,
+      observed: 1,
+      verified: 2,
+      conflict: 3
+    };
   }
 });
 
@@ -77,7 +83,7 @@ var init_constants = __esm({
     init_esm_shims();
     SERVER_NAME = "lurq";
     PACKAGE_NAME = "lurqrun";
-    VERSION = "0.0.4";
+    VERSION = "0.0.6";
     DEFAULT_ENDPOINT = "https://api.lurq.run/mcp";
     API_KEY_PREFIX = "lurq_live_";
     EMBEDDING_DIM = 1536;
@@ -95,18 +101,12 @@ var init_constants = __esm({
 });
 
 // src/core/config.ts
-var config_exports = {};
-__export(config_exports, {
-  ConfigError: () => ConfigError,
-  getConfig: () => getConfig,
-  loadEnv: () => loadEnv,
-  requireConfig: () => requireConfig,
-  resetConfigCache: () => resetConfigCache
-});
 import { config as dotenvConfig } from "dotenv";
 import { z } from "zod";
 function loadEnv() {
   if (envLoaded) return;
+  const overrideFile = process.env.LURQ_ENV_FILE;
+  if (overrideFile) dotenvConfig({ path: overrideFile });
   dotenvConfig();
   envLoaded = true;
 }
@@ -122,9 +122,6 @@ ${issues}`);
   cached = parsed.data;
   return cached;
 }
-function resetConfigCache() {
-  cached = void 0;
-}
 function requireConfig(keys) {
   const config = getConfig();
   const missing = keys.filter((k) => config[k] === void 0 || config[k] === "");
@@ -182,7 +179,9 @@ var init_config = __esm({
       E2B_API_KEY: z.string().min(1).optional(),
       // E2B template to launch. Must provide node + npm on PATH; omit for E2B's
       // default. Provision a Node-versioned template here for reproducible runs.
-      E2B_TEMPLATE: z.string().min(1).optional()
+      E2B_TEMPLATE: z.string().min(1).optional(),
+      // Lurq bakeoff testing toggle b/w local and prod DB
+      USE_LIVE_API: z.string().min(1).optional()
     });
     ConfigError = class extends Error {
       constructor(message) {
@@ -232,11 +231,19 @@ var init_logger = __esm({
 var schema_exports = {};
 __export(schema_exports, {
   apiKeys: () => apiKeys,
+  apiSurfaces: () => apiSurfaces,
+  claims: () => claims,
   compatEdges: () => compatEdges,
+  compatVerifyQueue: () => compatVerifyQueue,
   discoveryQueue: () => discoveryQueue,
+  entities: () => entities,
+  environments: () => environments,
+  observations: () => observations,
+  ownerUsageDaily: () => ownerUsageDaily,
   packageVersions: () => packageVersions,
   packages: () => packages,
   recommendationOutcomes: () => recommendationOutcomes,
+  resolvedClosures: () => resolvedClosures,
   seedPackages: () => seedPackages,
   syncRuns: () => syncRuns,
   verificationRuns: () => verificationRuns,
@@ -247,6 +254,7 @@ import {
   bigint,
   boolean,
   customType,
+  date,
   index,
   integer,
   jsonb,
@@ -259,7 +267,7 @@ import {
   uniqueIndex,
   vector
 } from "drizzle-orm/pg-core";
-var tsvector, ts, packages, syncRuns, seedPackages, discoveryQueue, apiKeys, packageVersions, watchState, verificationRuns, compatEdges, recommendationOutcomes;
+var tsvector, ts, packages, syncRuns, seedPackages, discoveryQueue, compatVerifyQueue, apiKeys, packageVersions, watchState, verificationRuns, compatEdges, resolvedClosures, apiSurfaces, recommendationOutcomes, ownerUsageDaily, entities, environments, claims, observations;
 var init_schema = __esm({
   "src/db/schema.ts"() {
     "use strict";
@@ -329,8 +337,19 @@ var init_schema = __esm({
         ),
         // Freshness + bookkeeping
         dataAsOf: timestamp("data_as_of", { withTimezone: true, mode: "date" }),
+        /** latest_version this package's direct deps were last expanded for by the
+         *  discovery graph channel (§2B). Discovery re-scans a package only when this
+         *  differs from latest_version — deps are version-pinned, so an unchanged
+         *  version has unchanged neighbors. NULL = never scanned. */
+        graphScannedVersion: text("graph_scanned_version"),
         createdAt: ts("created_at").notNull().defaultNow(),
-        updatedAt: ts("updated_at").notNull().defaultNow()
+        updatedAt: ts("updated_at").notNull().defaultNow(),
+        /** The individual account (api_keys.owner_id) whose on-demand query first
+         *  caused this package to be ingested — nobody had asked for it before them.
+         *  Null for crawler/_changes-created packages, or ones ingested before
+         *  dashboard accounts existed. Stamped once via a standalone WHERE ... IS NULL
+         *  update kept out of upsertPackage, so re-syncs can never clobber it. */
+        firstRequestedByOwnerId: text("first_requested_by_owner_id")
       },
       (table2) => [
         index("packages_category_idx").on(table2.category),
@@ -338,7 +357,8 @@ var init_schema = __esm({
         // pgvector HNSW index for cosine similarity search (§11).
         index("packages_embedding_idx").using("hnsw", table2.embedding.op("vector_cosine_ops")),
         // GIN index for lexical full-text search (§3).
-        index("packages_search_vector_idx").using("gin", table2.searchVector)
+        index("packages_search_vector_idx").using("gin", table2.searchVector),
+        index("packages_first_requested_by_idx").on(table2.firstRequestedByOwnerId)
       ]
     );
     syncRuns = pgTable("sync_runs", {
@@ -368,6 +388,20 @@ var init_schema = __esm({
       },
       (table2) => [index("discovery_queue_status_idx").on(table2.status)]
     );
+    compatVerifyQueue = pgTable(
+      "compat_verify_queue",
+      {
+        id: serial("id").primaryKey(),
+        /** Canonical order-independent key of the package set — dedups pending requests. */
+        setKey: text("set_key").notNull().unique(),
+        /** The package names to co-install in the sandbox. */
+        packages: jsonb("packages").$type().notNull(),
+        /** Failed drains bump this; the worker drops a set that keeps failing. */
+        attempts: integer("attempts").notNull().default(0),
+        requestedAt: ts("requested_at").notNull().defaultNow()
+      },
+      (table2) => [index("compat_verify_queue_requested_idx").on(table2.requestedAt)]
+    );
     apiKeys = pgTable(
       "api_keys",
       {
@@ -430,6 +464,12 @@ var init_schema = __esm({
         packageB: text("package_b").notNull(),
         versionB: text("version_b").notNull(),
         status: text("status").$type().notNull(),
+        /** Evidence class (§4B). Existing rows are sandbox co-installs, so the column
+         *  defaults to `verified` to preserve their meaning. */
+        provenance: text("provenance").$type().notNull().default("verified"),
+        /** Distinct resolved graphs an `observed` edge was witnessed in (confidence).
+         *  Ignored for verified/conflict. Accumulates on conflict, never overwritten. */
+        witnessCount: integer("witness_count").notNull().default(0),
         driver: text("driver").notNull(),
         ranAt: ts("ran_at")
       },
@@ -442,14 +482,40 @@ var init_schema = __esm({
         )
       ]
     );
+    resolvedClosures = pgTable(
+      "resolved_closures",
+      {
+        id: serial("id").primaryKey(),
+        packageName: text("package_name").notNull(),
+        version: text("version").notNull(),
+        /** Full closure: [{ name, version }, …] — every node in node_modules. */
+        nodes: jsonb("nodes").$type().notNull(),
+        fetchedAt: ts("fetched_at").notNull().defaultNow()
+      },
+      (table2) => [
+        uniqueIndex("resolved_closures_pkg_idx").on(table2.packageName, table2.version)
+      ]
+    );
+    apiSurfaces = pgTable(
+      "api_surfaces",
+      {
+        id: serial("id").primaryKey(),
+        packageName: text("package_name").notNull(),
+        version: text("version").notNull(),
+        /** Normalized export list: [{ name, kind, signature }, …]. */
+        surface: jsonb("surface").$type().notNull(),
+        extractedAt: ts("extracted_at").notNull().defaultNow()
+      },
+      (table2) => [uniqueIndex("api_surfaces_pkg_idx").on(table2.packageName, table2.version)]
+    );
     recommendationOutcomes = pgTable(
       "recommendation_outcomes",
       {
         id: serial("id").primaryKey(),
-        /** The org this outcome belongs to (api_keys.owner_id). Null for anonymous /
-         *  operator-issued keys. This is what turns the flywheel from a global blob
-         *  into a per-org asset — "what did *this* org succeed with." Server-injected
-         *  from the authenticated key, never caller-supplied. */
+        /** The individual user this outcome belongs to (api_keys.owner_id). Null for
+         *  anonymous/operator-issued keys. This is what turns the flywheel from a
+         *  global blob into a per-user asset — "what did *this* person succeed
+         *  with." Server-injected from the authenticated key, never caller-supplied. */
         ownerId: text("owner_id"),
         packageName: text("package_name").notNull(),
         accepted: boolean("accepted").notNull(),
@@ -464,6 +530,93 @@ var init_schema = __esm({
         index("recommendation_outcomes_owner_idx").on(table2.ownerId)
       ]
     );
+    ownerUsageDaily = pgTable(
+      "owner_usage_daily",
+      {
+        ownerId: text("owner_id").notNull(),
+        /** UTC day, 'YYYY-MM-DD'. */
+        date: date("date").notNull(),
+        /** recommend | evaluate | compare | compat | verify | usage | diagram | plan | report_outcome */
+        tool: text("tool").notNull(),
+        count: integer("count").notNull().default(0)
+      },
+      (table2) => [
+        primaryKey({ columns: [table2.ownerId, table2.date, table2.tool] }),
+        index("owner_usage_daily_owner_date_idx").on(table2.ownerId, table2.date)
+      ]
+    );
+    entities = pgTable(
+      "entities",
+      {
+        id: serial("id").primaryKey(),
+        kind: text("kind").$type().notNull(),
+        /** Registry or authority: npm, api.stripe.com, … */
+        namespace: text("namespace").notNull(),
+        name: text("name").notNull(),
+        /** Null for unversioned kinds. */
+        version: text("version"),
+        /** `kind:namespace:name:version` */
+        canonicalKey: text("canonical_key").notNull(),
+        /**
+         * 0 = the public graph; a real id = a private deployment's tenant. The spec
+         * models public as NULL, but Postgres UNIQUE treats NULLs as distinct, so
+         * (key, NULL) would insert unlimited duplicates and the dedup silently fails.
+         * A non-null sentinel is the cheap fix that works on every PG version.
+         */
+        tenantId: bigint("tenant_id", { mode: "number" }).notNull().default(0),
+        firstSeen: ts("first_seen").notNull().defaultNow()
+      },
+      (table2) => [
+        uniqueIndex("entities_canonical_idx").on(table2.canonicalKey, table2.tenantId),
+        index("entities_kind_idx").on(table2.kind, table2.namespace, table2.name)
+      ]
+    );
+    environments = pgTable("environments", {
+      id: serial("id").primaryKey(),
+      os: text("os").notNull(),
+      arch: text("arch").notNull(),
+      runtime: text("runtime").notNull(),
+      runtimeVer: text("runtime_ver").notNull(),
+      resolver: text("resolver"),
+      /** Hash of the above; the dedup key. */
+      fingerprint: text("fingerprint").notNull().unique()
+    });
+    claims = pgTable(
+      "claims",
+      {
+        id: serial("id").primaryKey(),
+        subjectId: integer("subject_id").notNull().references(() => entities.id),
+        /** Null for unary claims ("does this install at all"). */
+        objectId: integer("object_id").references(() => entities.id),
+        relation: text("relation").notNull(),
+        environmentId: integer("environment_id").notNull().references(() => environments.id),
+        tenantId: bigint("tenant_id", { mode: "number" }).notNull().default(0)
+      },
+      (table2) => [
+        uniqueIndex("claims_tuple_idx").on(
+          table2.subjectId,
+          table2.objectId,
+          table2.relation,
+          table2.environmentId,
+          table2.tenantId
+        )
+      ]
+    );
+    observations = pgTable(
+      "observations",
+      {
+        id: serial("id").primaryKey(),
+        claimId: integer("claim_id").notNull().references(() => claims.id),
+        verdict: text("verdict").$type().notNull(),
+        /** Evidence that makes the verdict auditable. Null only for `unknown`. */
+        evidence: text("evidence"),
+        oracleId: text("oracle_id").notNull(),
+        oracleVer: text("oracle_ver").notNull(),
+        costMillis: integer("cost_millis"),
+        observedAt: ts("observed_at").notNull().defaultNow()
+      },
+      (table2) => [index("observations_claim_idx").on(table2.claimId, table2.observedAt)]
+    );
   }
 });
 
@@ -472,10 +625,10 @@ import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 function createDb(opts = {}) {
   const { DATABASE_URL } = requireConfig(["DATABASE_URL"]);
-  const sql6 = postgres(DATABASE_URL, { max: opts.max ?? 10, onnotice: () => {
+  const sql8 = postgres(DATABASE_URL, { max: opts.max ?? 10, onnotice: () => {
   } });
-  const db = drizzle(sql6, { schema: schema_exports });
-  return { db, sql: sql6, close: () => sql6.end() };
+  const db = drizzle(sql8, { schema: schema_exports });
+  return { db, sql: sql8, close: () => sql8.end() };
 }
 var init_client = __esm({
   "src/db/client.ts"() {
@@ -573,7 +726,7 @@ var init_cache = __esm({
 });
 
 // src/db/compat.ts
-import { and, inArray } from "drizzle-orm";
+import { and, eq, inArray, sql as sql2 } from "drizzle-orm";
 async function getCompatMetadata(db, names) {
   if (names.length === 0) return [];
   return db.select({
@@ -588,26 +741,87 @@ function canonicalPair(a, b) {
   const [low, high] = a.name <= b.name ? [a, b] : [b, a];
   return { packageA: low.name, versionA: low.version, packageB: high.name, versionB: high.version };
 }
+function provenanceRank(col) {
+  return sql2`case ${col} when 'conflict' then 3 when 'verified' then 2 when 'observed' then 1 else 0 end`;
+}
+function conflictSet() {
+  const incomingWins = sql2`${provenanceRank(sql2`excluded.provenance`)} >= ${provenanceRank(compatEdges.provenance)}`;
+  return {
+    status: sql2`case when ${incomingWins} then excluded.status else ${compatEdges.status} end`,
+    provenance: sql2`case when ${incomingWins} then excluded.provenance else ${compatEdges.provenance} end`,
+    driver: sql2`case when ${incomingWins} then excluded.driver else ${compatEdges.driver} end`,
+    ranAt: sql2`case when ${incomingWins} then excluded.ran_at else ${compatEdges.ranAt} end`,
+    witnessCount: sql2`${compatEdges.witnessCount} + excluded.witness_count`
+  };
+}
 async function upsertCompatEdge(db, edge) {
-  await db.insert(compatEdges).values(edge).onConflictDoUpdate({
-    target: [
-      compatEdges.packageA,
-      compatEdges.versionA,
-      compatEdges.packageB,
-      compatEdges.versionB
-    ],
-    set: { status: edge.status, driver: edge.driver, ranAt: edge.ranAt }
+  await db.insert(compatEdges).values(edge).onConflictDoUpdate({ target: [...CONFLICT_TARGET], set: conflictSet() });
+}
+function chunk(items, size) {
+  if (size <= 0) throw new Error(`chunk size must be positive, got ${size}`);
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+async function upsertCompatEdgesBatch(db, edges) {
+  if (edges.length === 0) return;
+  for (const part of chunk(edges, EDGE_UPSERT_CHUNK)) {
+    await db.insert(compatEdges).values(part).onConflictDoUpdate({ target: [...CONFLICT_TARGET], set: conflictSet() });
+  }
+}
+async function persistClosure(db, packageName, version, nodes) {
+  await db.insert(resolvedClosures).values({ packageName, version, nodes }).onConflictDoUpdate({
+    target: [resolvedClosures.packageName, resolvedClosures.version],
+    set: { nodes, fetchedAt: /* @__PURE__ */ new Date() }
   });
 }
 async function getCompatEdges(db, names) {
   if (names.length === 0) return [];
   return db.select().from(compatEdges).where(and(inArray(compatEdges.packageA, names), inArray(compatEdges.packageB, names)));
 }
+function pairKey(a, b) {
+  return a <= b ? `${a}|${b}` : `${b}|${a}`;
+}
+function fullyCovered(batch, covered) {
+  for (let i = 0; i < batch.length; i++) {
+    for (let j = i + 1; j < batch.length; j++) {
+      if (!covered.has(pairKey(batch[i], batch[j]))) return false;
+    }
+  }
+  return true;
+}
+function compatSetKey(names) {
+  return [...new Set(names)].sort().join("|");
+}
+async function enqueueCompatVerify(db, names) {
+  const packages2 = [...new Set(names)].filter(Boolean);
+  if (packages2.length < 2) return false;
+  const inserted = await db.insert(compatVerifyQueue).values({ setKey: compatSetKey(packages2), packages: packages2 }).onConflictDoNothing({ target: compatVerifyQueue.setKey }).returning({ id: compatVerifyQueue.id });
+  return inserted.length > 0;
+}
+async function getPendingCompatVerify(db, limit) {
+  return db.select().from(compatVerifyQueue).orderBy(compatVerifyQueue.requestedAt).limit(limit);
+}
+async function deleteCompatVerify(db, id) {
+  await db.delete(compatVerifyQueue).where(eq(compatVerifyQueue.id, id));
+}
+async function bumpCompatVerifyAttempt(db, id) {
+  const [row] = await db.update(compatVerifyQueue).set({ attempts: sql2`${compatVerifyQueue.attempts} + 1` }).where(eq(compatVerifyQueue.id, id)).returning({ attempts: compatVerifyQueue.attempts });
+  return row?.attempts ?? 0;
+}
+var CONFLICT_TARGET, EDGE_UPSERT_CHUNK;
 var init_compat = __esm({
   "src/db/compat.ts"() {
     "use strict";
     init_esm_shims();
     init_schema();
+    CONFLICT_TARGET = [
+      compatEdges.packageA,
+      compatEdges.versionA,
+      compatEdges.packageB,
+      compatEdges.versionB
+    ];
+    EDGE_UPSERT_CHUNK = 250;
   }
 });
 
@@ -625,9 +839,6 @@ function limiterFor(host) {
   }
   return limiter;
 }
-function setCacheBypassRead(value) {
-  bypassCacheRead = value;
-}
 function cacheDir() {
   return process.env.LURQ_CACHE_DIR ?? join(homedir(), ".cache", "lurq", "http");
 }
@@ -732,8 +943,8 @@ function parseRetryAfter(value) {
   if (!value) return void 0;
   const seconds = Number(value);
   if (!Number.isNaN(seconds)) return seconds * 1e3;
-  const date = Date.parse(value);
-  return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+  const date2 = Date.parse(value);
+  return Number.isNaN(date2) ? void 0 : Math.max(0, date2 - Date.now());
 }
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -936,6 +1147,28 @@ async function fetchNpmRegistry(name, fetchImpl) {
   });
   return parseNpmRegistry(data);
 }
+async function fetchNpmCompatAtVersion(name, version, fetchImpl) {
+  const url = `https://${HOST}/${encodeNpmName(name)}`;
+  try {
+    const { data } = await httpGetJson(url, {
+      host: HOST,
+      ttlMs: CACHE_TTL.npmRegistry,
+      fetchImpl
+    });
+    const latest = data?.["dist-tags"]?.latest ?? null;
+    const wanted = version && data?.versions?.[version] ? version : latest && data?.versions?.[latest] ? latest : null;
+    if (!wanted) return null;
+    const manifest = data.versions[wanted] ?? {};
+    return {
+      version: wanted,
+      peerDependencies: parseDepMap(manifest.peerDependencies),
+      peerDependenciesMeta: parsePeerMeta(manifest.peerDependenciesMeta),
+      engines: parseDepMap(manifest.engines)
+    };
+  } catch {
+    return null;
+  }
+}
 async function npmPackageExists(name, fetchImpl) {
   const url = `https://${HOST}/${encodeNpmName(name)}`;
   try {
@@ -965,28 +1198,12 @@ var init_npmRegistry = __esm({
 });
 
 // src/ingestion/sources/npmSearch.ts
-async function searchNpm(query, size = 20, fetchImpl) {
-  const url = `https://${HOST2}/-/v1/search?text=${encodeURIComponent(query)}&size=${size}`;
-  try {
-    const { data } = await httpGetJson(url, {
-      host: HOST2,
-      ttlMs: CACHE_TTL.npmRegistry,
-      fetchImpl
-    });
-    const objects = Array.isArray(data?.objects) ? data.objects : [];
-    return objects.map((o) => ({ name: o?.package?.name, date: o?.package?.date ?? null })).filter((h) => typeof h.name === "string");
-  } catch {
-    return [];
-  }
-}
-var HOST2;
 var init_npmSearch = __esm({
   "src/ingestion/sources/npmSearch.ts"() {
     "use strict";
     init_esm_shims();
     init_constants();
     init_http();
-    HOST2 = "registry.npmjs.org";
   }
 });
 
@@ -1007,36 +1224,19 @@ function parseDownloadGrowth(json2) {
   if (priorAvg <= 0) return recentAvg > 0 ? 1 : 0;
   return Math.round((recentAvg - priorAvg) / priorAvg * 1e3) / 1e3;
 }
-function ymd(date) {
-  return date.toISOString().slice(0, 10);
+function ymd(date2) {
+  return date2.toISOString().slice(0, 10);
 }
 function last90DayRange(now = /* @__PURE__ */ new Date()) {
   const end = now;
   const start = new Date(end.getTime() - 90 * 24 * 60 * 60 * 1e3);
   return `${ymd(start)}:${ymd(end)}`;
 }
-function parseBulkWeekly(json2, requested) {
-  const map = /* @__PURE__ */ new Map();
-  if (json2 && typeof json2.downloads === "number" && typeof json2.package === "string") {
-    map.set(json2.package, json2.downloads);
-    return map;
-  }
-  for (const name of requested) {
-    const entry = json2?.[name];
-    map.set(name, entry && typeof entry.downloads === "number" ? entry.downloads : null);
-  }
-  return map;
-}
-function chunk(items, size) {
-  const out = [];
-  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
-  return out;
-}
 async function fetchWeeklyDownloads(name, fetchImpl) {
   try {
     const { data } = await httpGetJson(
-      `https://${HOST3}/downloads/point/last-week/${name}`,
-      { host: HOST3, ttlMs: CACHE_TTL.npmDownloads, retries: 5, fetchImpl }
+      `https://${HOST2}/downloads/point/last-week/${name}`,
+      { host: HOST2, ttlMs: CACHE_TTL.npmDownloads, retries: 5, fetchImpl }
     );
     return parseWeeklyDownloads(data);
   } catch (err) {
@@ -1047,45 +1247,22 @@ async function fetchWeeklyDownloads(name, fetchImpl) {
 async function fetchDownloadGrowth(name, fetchImpl) {
   try {
     const { data } = await httpGetJson(
-      `https://${HOST3}/downloads/range/${last90DayRange()}/${name}`,
-      { host: HOST3, ttlMs: CACHE_TTL.npmDownloads, retries: 3, fetchImpl }
+      `https://${HOST2}/downloads/range/${last90DayRange()}/${name}`,
+      { host: HOST2, ttlMs: CACHE_TTL.npmDownloads, retries: 3, fetchImpl }
     );
     return parseDownloadGrowth(data);
   } catch {
     return null;
   }
 }
-async function fetchBulkWeeklyDownloads(names, fetchImpl) {
-  const result = /* @__PURE__ */ new Map();
-  const unscoped = names.filter((n) => !n.startsWith("@"));
-  const scoped = names.filter((n) => n.startsWith("@"));
-  for (const batch of chunk(unscoped, BULK_CHUNK)) {
-    try {
-      const { data } = await httpGetJson(
-        `https://${HOST3}/downloads/point/last-week/${batch.join(",")}`,
-        { host: HOST3, ttlMs: CACHE_TTL.npmDownloads, retries: 5, fetchImpl }
-      );
-      for (const [k, v] of parseBulkWeekly(data, batch)) result.set(k, v);
-    } catch {
-    }
-  }
-  for (const name of scoped) {
-    try {
-      result.set(name, await fetchWeeklyDownloads(name, fetchImpl));
-    } catch {
-    }
-  }
-  return result;
-}
-var HOST3, BULK_CHUNK;
+var HOST2;
 var init_npmDownloads = __esm({
   "src/ingestion/sources/npmDownloads.ts"() {
     "use strict";
     init_esm_shims();
     init_constants();
     init_http();
-    HOST3 = "api.npmjs.org";
-    BULK_CHUNK = 128;
+    HOST2 = "api.npmjs.org";
   }
 });
 
@@ -1108,7 +1285,7 @@ function parseGithub(json2, now = /* @__PURE__ */ new Date()) {
 async function fetchGithubRepo(owner, repo, token, fetchImpl) {
   const body = JSON.stringify({ query: QUERY, variables: { owner, name: repo } });
   const { data } = await httpRequest(ENDPOINT, {
-    host: HOST4,
+    host: HOST3,
     ttlMs: CACHE_TTL.github,
     method: "POST",
     headers: {
@@ -1123,15 +1300,15 @@ async function fetchGithubRepo(owner, repo, token, fetchImpl) {
   });
   return parseGithub(data);
 }
-var HOST4, ENDPOINT, QUERY, ONE_YEAR_MS;
+var HOST3, ENDPOINT, QUERY, ONE_YEAR_MS;
 var init_github = __esm({
   "src/ingestion/sources/github.ts"() {
     "use strict";
     init_esm_shims();
     init_constants();
     init_http();
-    HOST4 = "api.github.com";
-    ENDPOINT = `https://${HOST4}/graphql`;
+    HOST3 = "api.github.com";
+    ENDPOINT = `https://${HOST3}/graphql`;
     QUERY = `query($owner:String!, $name:String!) {
   repository(owner:$owner, name:$name) {
     stargazerCount
@@ -1177,10 +1354,10 @@ function parseAdvisoryDetail(json2) {
 }
 async function fetchScorecard(owner, repo, fetchImpl) {
   const projectKey = encodeURIComponent(`github.com/${owner}/${repo}`);
-  const url = `https://${HOST5}/v3/projects/${projectKey}`;
+  const url = `https://${HOST4}/v3/projects/${projectKey}`;
   try {
     const { data } = await httpGetJson(url, {
-      host: HOST5,
+      host: HOST4,
       ttlMs: CACHE_TTL.depsDev,
       fetchImpl
     });
@@ -1190,11 +1367,11 @@ async function fetchScorecard(owner, repo, fetchImpl) {
   }
 }
 async function fetchAdvisories(name, version, fetchImpl) {
-  const versionUrl = `https://${HOST5}/v3/systems/npm/packages/${encodeName(name)}/versions/${encodeURIComponent(version)}`;
+  const versionUrl = `https://${HOST4}/v3/systems/npm/packages/${encodeName(name)}/versions/${encodeURIComponent(version)}`;
   let keys = [];
   try {
     const { data } = await httpGetJson(versionUrl, {
-      host: HOST5,
+      host: HOST4,
       ttlMs: CACHE_TTL.depsDev,
       fetchImpl
     });
@@ -1204,8 +1381,8 @@ async function fetchAdvisories(name, version, fetchImpl) {
   }
   const details = await Promise.allSettled(
     keys.map(
-      (key) => httpGetJson(`https://${HOST5}/v3/advisories/${encodeURIComponent(key)}`, {
-        host: HOST5,
+      (key) => httpGetJson(`https://${HOST4}/v3/advisories/${encodeURIComponent(key)}`, {
+        host: HOST4,
         ttlMs: CACHE_TTL.depsDev,
         fetchImpl
       })
@@ -1215,17 +1392,27 @@ async function fetchAdvisories(name, version, fetchImpl) {
     (d) => d.status === "fulfilled"
   ).map((d) => parseAdvisoryDetail(d.value.data));
 }
-async function fetchDependencyNames(name, version, fetchImpl) {
-  const url = `https://${HOST5}/v3/systems/npm/packages/${encodeName(name)}/versions/${encodeURIComponent(version)}:dependencies`;
+async function fetchResolvedGraph(name, version, fetchImpl) {
+  const url = `https://${HOST4}/v3/systems/npm/packages/${encodeName(name)}/versions/${encodeURIComponent(version)}:dependencies`;
   try {
     const { data } = await httpGetJson(url, {
-      host: HOST5,
+      host: HOST4,
       ttlMs: CACHE_TTL.depsDev,
       fetchImpl
     });
     const nodes = Array.isArray(data?.nodes) ? data.nodes : [];
-    const names = nodes.map((n) => n?.versionKey?.name).filter((n) => typeof n === "string" && n !== name);
-    return [...new Set(names)];
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const n of nodes) {
+      const nm = n?.versionKey?.name;
+      const ver = n?.versionKey?.version;
+      if (typeof nm !== "string" || typeof ver !== "string") continue;
+      const key = `${nm}@${ver}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ name: nm, version: ver });
+    }
+    return out;
   } catch {
     return [];
   }
@@ -1237,14 +1424,14 @@ async function fetchDepsDev(name, version, repo, fetchImpl) {
   ]);
   return { scorecard, advisories };
 }
-var HOST5, MAX_ADVISORIES;
+var HOST4, MAX_ADVISORIES;
 var init_depsDev = __esm({
   "src/ingestion/sources/depsDev.ts"() {
     "use strict";
     init_esm_shims();
     init_constants();
     init_http();
-    HOST5 = "api.deps.dev";
+    HOST4 = "api.deps.dev";
     MAX_ADVISORIES = 10;
   }
 });
@@ -1257,10 +1444,10 @@ function parseBundleSize(json2) {
 }
 async function fetchBundlephobia(name, category, fetchImpl) {
   if (!isFrontendCategory(category)) return { bundleMinGzipKb: null };
-  const url = `https://${HOST6}/api/size?package=${encodeURIComponent(name)}`;
+  const url = `https://${HOST5}/api/size?package=${encodeURIComponent(name)}`;
   try {
     const { data } = await httpGetJson(url, {
-      host: HOST6,
+      host: HOST5,
       ttlMs: CACHE_TTL.bundlephobia,
       timeoutMs: 12e3,
       retries: 1,
@@ -1271,7 +1458,7 @@ async function fetchBundlephobia(name, category, fetchImpl) {
     return { bundleMinGzipKb: null };
   }
 }
-var HOST6;
+var HOST5;
 var init_bundlephobia = __esm({
   "src/ingestion/sources/bundlephobia.ts"() {
     "use strict";
@@ -1279,7 +1466,7 @@ var init_bundlephobia = __esm({
     init_constants();
     init_http();
     init_types();
-    HOST6 = "bundlephobia.com";
+    HOST5 = "bundlephobia.com";
   }
 });
 
@@ -1298,34 +1485,55 @@ var init_sources = __esm({
 });
 
 // src/compat/members.ts
-async function assembleMembers(db, names) {
+async function assembleMembers(db, refs) {
+  const normalized = refs.map(
+    (r) => typeof r === "string" ? { name: r, version: null } : r
+  );
+  const names = [...new Set(normalized.map((r) => r.name))];
   const tracked = new Map((await getCompatMetadata(db, names)).map((r) => [r.name, r]));
   const members = [];
   const unverified = [];
   await Promise.all(
-    names.map(async (name) => {
-      const row = tracked.get(name);
-      if (row) {
+    normalized.map(async (ref) => {
+      const row = tracked.get(ref.name);
+      const pin = ref.version?.trim() || null;
+      const canUseIndexed = row && (!pin || !row.latestVersion || pin === row.latestVersion);
+      if (canUseIndexed && row) {
         members.push({
-          name,
-          version: row.latestVersion,
+          name: ref.name,
+          version: pin ?? row.latestVersion,
           peerDependencies: row.peerDependencies,
           peerDependenciesMeta: row.peerDependenciesMeta,
           engines: row.engines
         });
         return;
       }
-      const reg = await fetchNpmRegistry(name).catch(() => null);
+      if (pin) {
+        const at = await fetchNpmCompatAtVersion(ref.name, pin).catch(() => null);
+        if (at) {
+          members.push({
+            name: ref.name,
+            version: at.version,
+            peerDependencies: at.peerDependencies,
+            peerDependenciesMeta: at.peerDependenciesMeta,
+            engines: at.engines
+          });
+          return;
+        }
+        unverified.push(ref.name);
+        return;
+      }
+      const reg = await fetchNpmRegistry(ref.name).catch(() => null);
       if (reg) {
         members.push({
-          name,
+          name: ref.name,
           version: reg.latestVersion,
           peerDependencies: reg.peerDependencies,
           peerDependenciesMeta: reg.peerDependenciesMeta,
           engines: reg.engines
         });
       } else {
-        unverified.push(name);
+        unverified.push(ref.name);
       }
     })
   );
@@ -1416,6 +1624,30 @@ function resolveArchitectureCompat(members) {
   }
   return conflicts;
 }
+function resolveRuntimeEngineConflicts(members, nodeVersion) {
+  const runtime = normalizeNodeVersion(nodeVersion);
+  if (!runtime) return [];
+  const conflicts = [];
+  for (const m of members) {
+    const range = m.engines?.node;
+    if (!range) continue;
+    if (satisfiesRange(runtime, range) === false) {
+      conflicts.push({
+        source: "engines",
+        packages: [m.name],
+        detail: `${m.name}@${m.version ?? "?"} needs node ${range}, but the runtime is node ${runtime}`
+      });
+    }
+  }
+  return conflicts;
+}
+function normalizeNodeVersion(raw) {
+  const trimmed = raw.trim().replace(/^v/i, "");
+  if (!trimmed) return null;
+  if (semver.valid(trimmed)) return trimmed;
+  const coerced = semver.coerce(trimmed);
+  return coerced?.version ?? null;
+}
 var init_peerCompat = __esm({
   "src/compat/peerCompat.ts"() {
     "use strict";
@@ -1424,11 +1656,33 @@ var init_peerCompat = __esm({
 });
 
 // src/compat/check.ts
-async function checkCompat(db, packages2) {
+function gradeOverall(args) {
+  if (args.hasConflict) return "conflict";
+  if (args.hasUnverifiedMember) return "unknown";
+  if (args.memberNames.length < 2 || fullyCovered(args.memberNames, args.provenCompatible))
+    return "compatible";
+  return "likely";
+}
+async function checkCompat(db, packages2, opts = {}) {
   const names = [...new Set(packages2)];
-  const { members, unverified } = await assembleMembers(db, names);
-  const conflicts = resolveArchitectureCompat(members);
-  for (const edge of await getCompatEdges(db, names)) {
+  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 getCompatEdges(db, names);
+  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") {
       conflicts.push({
         source: "sandbox",
@@ -1437,13 +1691,27 @@ async function checkCompat(db, packages2) {
       });
     }
   }
-  const overall = conflicts.length ? "conflict" : unverified.length ? "unknown" : "compatible";
+  const checkedNames = members.map((m) => m.name);
+  const provenCompatible = new Set(
+    edges.filter((e) => e.status === "compatible").map((e) => pairKey(e.packageA, e.packageB))
+  );
+  if (checkedNames.length >= 2 && !conflicts.length && !fullyCovered(checkedNames, provenCompatible)) {
+    await enqueueCompatVerify(db, checkedNames).catch(() => {
+    });
+  }
+  const overall = gradeOverall({
+    hasConflict: conflicts.length > 0,
+    hasUnverifiedMember: unverified.length > 0,
+    memberNames: checkedNames,
+    provenCompatible
+  });
   return {
     packages: names,
     overall,
     conflicts,
     unverified,
-    checked: members.map((m) => ({ name: m.name, version: m.version }))
+    checked: members.map((m) => ({ name: m.name, version: m.version })),
+    evidence
   };
 }
 var init_check = __esm({
@@ -1457,13 +1725,9 @@ var init_check = __esm({
 });
 
 // src/db/packages.ts
-import { desc, eq, isNotNull } from "drizzle-orm";
-async function getSeedTargets(db) {
-  const rows = await db.select({ name: seedPackages.name, category: seedPackages.category }).from(seedPackages);
-  return rows.map((r) => ({ name: r.name, category: r.category ?? null }));
-}
+import { and as and2, desc, eq as eq2, isNotNull, isNull, sql as sql3 } from "drizzle-orm";
 async function getPackageByName(db, name) {
-  const rows = await db.select().from(packages).where(eq(packages.name, name)).limit(1);
+  const rows = await db.select().from(packages).where(eq2(packages.name, name)).limit(1);
   return rows[0] ?? null;
 }
 async function getAllPackageNames(db) {
@@ -1482,7 +1746,7 @@ async function upsertPackageVersions(db, name, versions) {
   }
 }
 async function getPackageVersions(db, name, limit = 50) {
-  const rows = await db.select({ version: packageVersions.version, publishedAt: packageVersions.publishedAt }).from(packageVersions).where(eq(packageVersions.packageName, name)).orderBy(desc(packageVersions.publishedAt)).limit(limit);
+  const rows = await db.select({ version: packageVersions.version, publishedAt: packageVersions.publishedAt }).from(packageVersions).where(eq2(packageVersions.packageName, name)).orderBy(desc(packageVersions.publishedAt)).limit(limit);
   return rows.map((r) => ({ version: r.version, publishedAt: r.publishedAt }));
 }
 async function getTopPackageNames(db, limit = 1e3) {
@@ -1499,18 +1763,22 @@ async function upsertPackage(db, row) {
     set: { ...mutable, updatedAt: /* @__PURE__ */ new Date() }
   });
 }
-async function startSyncRun(db) {
-  const [row] = await db.insert(syncRuns).values({ status: "running" }).returning({ id: syncRuns.id });
-  return row.id;
+async function stampFirstRequester(db, name, ownerId) {
+  await db.update(packages).set({ firstRequestedByOwnerId: ownerId }).where(and2(eq2(packages.name, name), isNull(packages.firstRequestedByOwnerId)));
 }
-async function finishSyncRun(db, id, data) {
-  await db.update(syncRuns).set({
-    finishedAt: /* @__PURE__ */ new Date(),
-    packagesSeen: data.packagesSeen,
-    packagesUpdated: data.packagesUpdated,
-    errors: data.errors,
-    status: data.status
-  }).where(eq(syncRuns.id, id));
+async function getContributionsByOwner(db, ownerId, opts = {}) {
+  const limit = opts.limit ?? 50;
+  const offset = opts.offset ?? 0;
+  const [rows, [countRow]] = await Promise.all([
+    db.select({
+      name: packages.name,
+      category: packages.category,
+      healthScore: packages.healthScore,
+      firstRequestedAt: packages.createdAt
+    }).from(packages).where(eq2(packages.firstRequestedByOwnerId, ownerId)).orderBy(desc(packages.createdAt)).limit(limit).offset(offset),
+    db.select({ count: sql3`count(*)::int` }).from(packages).where(eq2(packages.firstRequestedByOwnerId, ownerId))
+  ]);
+  return { total: countRow?.count ?? 0, packages: rows };
 }
 var VERSION_CHUNK;
 var init_packages = __esm({
@@ -1522,13 +1790,72 @@ var init_packages = __esm({
   }
 });
 
+// src/db/apiSurfaces.ts
+import { and as and3, eq as eq3, isNotNull as isNotNull2, isNull as isNull2 } from "drizzle-orm";
+async function getStoredSurface(db, packageName, version) {
+  const [row] = await db.select({ surface: apiSurfaces.surface }).from(apiSurfaces).where(and3(eq3(apiSurfaces.packageName, packageName), eq3(apiSurfaces.version, version))).limit(1);
+  return row?.surface ?? null;
+}
+var init_apiSurfaces = __esm({
+  "src/db/apiSurfaces.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_schema();
+  }
+});
+
+// src/usage/diff.ts
+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
+  };
+}
+var init_diff = __esm({
+  "src/usage/diff.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/db/verification.ts
-import { and as and2, desc as desc2, eq as eq2 } from "drizzle-orm";
+import { and as and4, desc as desc2, eq as eq4 } from "drizzle-orm";
 async function storeVerificationRun(db, run) {
   await db.insert(verificationRuns).values(run);
 }
 async function getLatestVerificationByName(db, packageName) {
-  const rows = await db.select().from(verificationRuns).where(eq2(verificationRuns.packageName, packageName)).orderBy(desc2(verificationRuns.ranAt)).limit(1);
+  const rows = await db.select().from(verificationRuns).where(eq4(verificationRuns.packageName, packageName)).orderBy(desc2(verificationRuns.ranAt)).limit(1);
   return rows[0] ?? null;
 }
 var init_verification = __esm({
@@ -1540,9 +1867,13 @@ var init_verification = __esm({
 });
 
 // src/db/outcomes.ts
+import { desc as desc3, eq as eq5 } from "drizzle-orm";
 async function recordOutcome(db, outcome) {
   await db.insert(recommendationOutcomes).values(outcome);
 }
+async function getOutcomesByOwner(db, ownerId, opts = {}) {
+  return db.select().from(recommendationOutcomes).where(eq5(recommendationOutcomes.ownerId, ownerId)).orderBy(desc3(recommendationOutcomes.createdAt)).limit(opts.limit ?? 50);
+}
 var init_outcomes = __esm({
   "src/db/outcomes.ts"() {
     "use strict";
@@ -1630,10 +1961,10 @@ var init_successors2 = __esm({
 // src/ingestion/sources/githubReadme.ts
 async function fetchGithubReadme(owner, repo, fetchImpl) {
   for (const file of CANDIDATES) {
-    const url = `https://${HOST7}/${owner}/${repo}/HEAD/${file}`;
+    const url = `https://${HOST6}/${owner}/${repo}/HEAD/${file}`;
     try {
       const { data } = await httpRequest(url, {
-        host: HOST7,
+        host: HOST6,
         ttlMs: CACHE_TTL.github,
         accept: "text",
         retries: 0,
@@ -1645,14 +1976,14 @@ async function fetchGithubReadme(owner, repo, fetchImpl) {
   }
   return null;
 }
-var HOST7, CANDIDATES;
+var HOST6, CANDIDATES;
 var init_githubReadme = __esm({
   "src/ingestion/sources/githubReadme.ts"() {
     "use strict";
     init_esm_shims();
     init_constants();
     init_http();
-    HOST7 = "raw.githubusercontent.com";
+    HOST6 = "raw.githubusercontent.com";
     CANDIDATES = ["README.md", "readme.md", "README.markdown", "README"];
   }
 });
@@ -1950,12 +2281,6 @@ function packageRoot() {
   cachedRoot = process.cwd();
   return cachedRoot;
 }
-function migrationsDir() {
-  return join2(packageRoot(), "drizzle");
-}
-function seedJsonPath() {
-  return join2(packageRoot(), "src", "data", "seed.json");
-}
 function userWeightsPath() {
   const base = process.env.XDG_CONFIG_HOME || join2(homedir2(), ".config");
   return join2(base, "lurq", "weights.json");
@@ -2033,10 +2358,10 @@ function settableKeys() {
 function applyOverrides(base, sets) {
   const next = structuredClone(base);
   for (const entry of sets) {
-    const eq9 = entry.indexOf("=");
-    if (eq9 < 0) throw new Error(`Invalid --set "${entry}" (expected key=value).`);
-    const key = entry.slice(0, eq9).trim();
-    const value = Number(entry.slice(eq9 + 1).trim());
+    const eq11 = entry.indexOf("=");
+    if (eq11 < 0) throw new Error(`Invalid --set "${entry}" (expected key=value).`);
+    const key = entry.slice(0, eq11).trim();
+    const value = Number(entry.slice(eq11 + 1).trim());
     const apply = SETTABLE[key];
     if (!apply) {
       throw new Error(`Unknown weight key "${key}". Settable: ${settableKeys().join(", ")}.`);
@@ -2064,7 +2389,7 @@ function resetWeights() {
   resetWeightsCache();
   return removed;
 }
-var HEALTH_WEIGHTS, COMPOSITE, QUALITY_WEIGHTS, QUALITY, MAINTENANCE_WEIGHTS, MAINTENANCE, ADOPTION, RELIABILITY, EFFICIENCY, DISCOVERY, DEFAULT_WEIGHTS, cachedWeights, SETTABLE, WEIGHT_EXPLANATIONS, CONFIDENCE;
+var HEALTH_WEIGHTS, COMPOSITE, QUALITY_WEIGHTS, QUALITY, MAINTENANCE_WEIGHTS, MAINTENANCE, ADOPTION, RELIABILITY, EFFICIENCY, DEFAULT_WEIGHTS, cachedWeights, SETTABLE, WEIGHT_EXPLANATIONS, CONFIDENCE;
 var init_weights = __esm({
   "src/scoring/weights.ts"() {
     "use strict";
@@ -2143,16 +2468,6 @@ var init_weights = __esm({
       /** Bundle size at the category median maps to this score; smaller → higher. */
       medianScore: 50
     };
-    DISCOVERY = {
-      /** A queued candidate must clear this quality pre-score to graduate to ingest. */
-      minPreScore: 45,
-      /** Max candidates fully ingested per crawler run (cost bound). */
-      perRunCap: 25,
-      /** npm-search hits to pull per category keyword. */
-      searchSizePerCategory: 10,
-      /** Max dependency-graph neighbors to enqueue per tracked seed. */
-      graphNeighborsPerSeed: 20
-    };
     DEFAULT_WEIGHTS = {
       health: { ...HEALTH_WEIGHTS },
       composite: { ...COMPOSITE }
@@ -2368,12 +2683,6 @@ function weightedAverage(components) {
   if (totalWeight === 0) return 0;
   return Math.round(components.reduce((s, c) => s + c.value * c.weight, 0) / totalWeight);
 }
-function median(values) {
-  if (values.length === 0) return null;
-  const sorted = [...values].sort((a, b) => a - b);
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
-}
 var DAY_MS, MONTH_MS, clamp, daysSince, monthsSince, RECOGNIZED_LICENSES;
 var init_score = __esm({
   "src/scoring/score.ts"() {
@@ -2384,8 +2693,8 @@ var init_score = __esm({
     DAY_MS = 24 * 60 * 60 * 1e3;
     MONTH_MS = 30 * DAY_MS;
     clamp = (n, lo = 0, hi = 100) => Math.max(lo, Math.min(hi, n));
-    daysSince = (date, now) => date ? (now.getTime() - date.getTime()) / DAY_MS : null;
-    monthsSince = (date, now) => date ? (now.getTime() - date.getTime()) / MONTH_MS : null;
+    daysSince = (date2, now) => date2 ? (now.getTime() - date2.getTime()) / DAY_MS : null;
+    monthsSince = (date2, now) => date2 ? (now.getTime() - date2.getTime()) / MONTH_MS : null;
     RECOGNIZED_LICENSES = [
       "mit",
       "isc",
@@ -2530,19 +2839,6 @@ var init_embeddings = __esm({
 });
 
 // src/core/concurrency.ts
-async function pMap(items, mapper, concurrency) {
-  const results = new Array(items.length);
-  let cursor = 0;
-  const workerCount = Math.max(1, Math.min(concurrency, items.length));
-  const workers = Array.from({ length: workerCount }, async () => {
-    while (cursor < items.length) {
-      const index2 = cursor++;
-      results[index2] = await mapper(items[index2], index2);
-    }
-  });
-  await Promise.all(workers);
-  return results;
-}
 var init_concurrency = __esm({
   "src/core/concurrency.ts"() {
     "use strict";
@@ -2550,172 +2846,93 @@ var init_concurrency = __esm({
   }
 });
 
-// src/pipeline/sync.ts
-async function runSync(opts = {}) {
-  const config = getConfig();
-  const now = /* @__PURE__ */ new Date();
-  if (opts.full) setCacheBypassRead(true);
-  const handle = createDb({ max: Math.max(4, config.LURQ_SYNC_CONCURRENCY) });
-  const provider = createSummaryProvider();
-  logger.info(`Summary provider: ${provider.kind}`);
-  if (!config.GITHUB_TOKEN) {
-    logger.warn(
-      "GITHUB_TOKEN not set \u2014 GitHub signals (stars, issues, release cadence) will be skipped, degrading maintenance/adoption scores. Set it for accurate scoring."
-    );
+// src/core/errors.ts
+function truncate(text2, max) {
+  if (text2.length <= max) return text2;
+  return `${text2.slice(0, max)}\u2026`;
+}
+function causeText(cause) {
+  if (cause == null) return null;
+  if (cause instanceof Error) {
+    const code = "code" in cause && (typeof cause.code === "string" || typeof cause.code === "number") ? String(cause.code) : null;
+    const msg = truncate(cause.message, DEFAULT_MAX);
+    return code ? `${code}: ${msg}` : msg;
+  }
+  if (typeof cause === "object" && cause !== null && "message" in cause) {
+    const msg = truncate(String(cause.message), DEFAULT_MAX);
+    const code = "code" in cause ? String(cause.code) : null;
+    return code ? `${code}: ${msg}` : msg;
+  }
+  return truncate(String(cause), DEFAULT_MAX);
+}
+function formatError(err, max = DEFAULT_MAX) {
+  const message = err instanceof Error ? truncate(err.message, max) : truncate(String(err), max);
+  const cause = err instanceof Error ? causeText(err.cause) : null;
+  return cause ? `${message} (cause: ${cause})` : message;
+}
+var DEFAULT_MAX;
+var init_errors = __esm({
+  "src/core/errors.ts"() {
+    "use strict";
+    init_esm_shims();
+    DEFAULT_MAX = 300;
   }
-  const runId = await startSyncRun(handle.db);
-  const allErrors = [];
-  try {
-    const targets = await resolveTargets(handle.db, opts);
-    logger.info(`Syncing ${targets.length} package(s) with concurrency ${config.LURQ_SYNC_CONCURRENCY}\u2026`);
-    logger.info("Fetching weekly downloads in bulk\u2026");
-    const weeklyMap = await fetchBulkWeeklyDownloads(targets.map((t) => t.name));
-    let done = 0;
-    const computed = await pMap(
-      targets,
-      async (target) => {
-        try {
-          const signals = await collectSignals(target.name, target.category, {
-            githubToken: config.GITHUB_TOKEN,
-            prefetchedWeekly: weeklyMap.has(target.name) ? weeklyMap.get(target.name) : void 0
-          });
-          for (const e of signals.errors) allErrors.push({ package: target.name, ...e });
-          const summaryInput = await buildSummaryInput(signals, target.category);
-          const { summary, usageGuide, inferredCategory } = await provider.generate(summaryInput);
-          let category = target.category;
-          let categorySource = target.category ? "curated" : null;
-          if (!category) {
-            category = inferCategoryFromSignals(signals) ?? inferredCategory ?? null;
-            categorySource = category ? "inferred" : null;
-          }
-          const input = toScoringInput(signals, category);
-          const quality = computeQuality(input);
-          if (++done % 25 === 0) logger.info(`  \u2026${done}/${targets.length}`);
-          return {
-            target,
-            category,
-            categorySource,
-            signals,
-            input,
-            maintenance: computeMaintenance(input, now),
-            adoption: computeAdoption(input),
-            reliability: computeReliability(input),
-            quality,
-            confidence: computeConfidence(input, now, quality),
-            summary,
-            usageGuide
-          };
-        } catch (err) {
-          allErrors.push({
-            package: target.name,
-            source: "pipeline",
-            message: err instanceof Error ? err.message : String(err)
-          });
-          return null;
-        }
-      },
-      config.LURQ_SYNC_CONCURRENCY
-    );
-    const ok = computed.filter((c) => c !== null);
-    const medians = computeCategoryMedians(ok);
-    const embProvider = createEmbeddingProvider();
-    logger.info(`Embedding provider: ${embProvider.kind}`);
-    const embeddings = await embProvider.embed(
-      ok.map(
-        (c) => buildEmbeddingText({
-          name: c.target.name,
-          category: c.category,
-          summary: c.summary,
-          description: c.signals.registry?.description ?? null
-        })
-      )
-    );
-    let updated = 0;
-    for (let i = 0; i < ok.length; i++) {
-      const c = ok[i];
-      const efficiency = computeEfficiency(
-        c.input.bundleMinGzipKb,
-        c.category,
-        c.category ? medians.get(c.category) ?? null : null
-      );
-      const breakdown = {
-        maintenance: c.maintenance,
-        adoption: c.adoption,
-        reliability: c.reliability,
-        efficiency,
-        quality: c.quality
-      };
-      const healthScore = computeHealthScore(breakdown);
-      await upsertPackage(
-        handle.db,
-        assemblePackageRow({
-          name: c.target.name,
-          category: c.category,
-          categorySource: c.categorySource,
-          signals: c.signals,
-          input: c.input,
-          summary: c.summary,
-          usageGuide: c.usageGuide,
-          confidence: c.confidence,
-          breakdown,
-          healthScore,
-          qualityScore: c.quality,
-          embedding: embeddings[i] ?? null,
-          embeddingProvider: embProvider.id,
-          now
-        })
-      );
-      updated++;
+});
+
+// src/pipeline/mineEdges.ts
+function trackedPairs(nodes, tracked) {
+  const t = nodes.filter((n) => tracked.has(n.name));
+  const pairs = [];
+  for (let i = 0; i < t.length; i++) {
+    for (let j = i + 1; j < t.length; j++) {
+      if (t[i].name === t[j].name) continue;
+      pairs.push(canonicalPair(t[i], t[j]));
     }
-    const status = updated === 0 ? "failed" : allErrors.length > 0 ? "partial" : "success";
-    await finishSyncRun(handle.db, runId, {
-      packagesSeen: targets.length,
-      packagesUpdated: updated,
-      errors: allErrors,
-      status
-    });
-    logger.info(`Sync ${status}: ${updated}/${targets.length} updated, ${allErrors.length} source errors.`);
-    if (updated > 0) await invalidateCache();
-    return { seen: targets.length, updated, errors: allErrors.length, status };
-  } catch (err) {
-    await finishSyncRun(handle.db, runId, {
-      packagesSeen: 0,
-      packagesUpdated: 0,
-      errors: [{ package: "*", source: "pipeline", message: err.message }],
-      status: "failed"
-    });
-    throw err;
-  } finally {
-    if (opts.full) setCacheBypassRead(false);
-    await handle.close();
   }
+  return pairs;
 }
-async function resolveTargets(db, opts) {
-  if (opts.packageName) {
-    const seeds = await getSeedTargets(db);
-    const found = seeds.find((s) => s.name === opts.packageName);
-    return [{ name: opts.packageName, category: found?.category ?? null }];
-  }
-  return getSeedTargets(db);
+async function mintObservedPairs(db, nodes, tracked, now) {
+  const pairs = trackedPairs(nodes, tracked);
+  await upsertCompatEdgesBatch(
+    db,
+    pairs.map((pair) => ({
+      ...pair,
+      status: "compatible",
+      provenance: "observed",
+      witnessCount: 1,
+      driver: "depsdev",
+      ranAt: now
+    }))
+  );
+  return pairs.length;
 }
-function computeCategoryMedians(computed) {
-  const byCategory = /* @__PURE__ */ new Map();
-  for (const c of computed) {
-    const cat = c.category;
-    const kb = c.input.bundleMinGzipKb;
-    if (cat && isFrontendCategory(cat) && kb !== null) {
-      const list = byCategory.get(cat) ?? [];
-      list.push(kb);
-      byCategory.set(cat, list);
-    }
-  }
-  const medians = /* @__PURE__ */ new Map();
-  for (const [cat, list] of byCategory) {
-    const m = median(list);
-    if (m !== null) medians.set(cat, m);
+async function mineEdgesForPackage(db, name, version, tracked, now = /* @__PURE__ */ new Date()) {
+  if (!version) return 0;
+  try {
+    const closure = await fetchResolvedGraph(name, version);
+    if (closure.length === 0) return 0;
+    await persistClosure(db, name, version, closure).catch(() => {
+    });
+    const set = tracked ?? new Set(await getAllPackageNames(db));
+    return await mintObservedPairs(db, closure, set, now);
+  } catch (err) {
+    logger.warn(`edge mining failed for ${name}@${version}: ${formatError(err)}`);
+    return 0;
   }
-  return medians;
 }
+var init_mineEdges = __esm({
+  "src/pipeline/mineEdges.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    init_logger();
+    init_packages();
+    init_compat();
+    init_depsDev();
+  }
+});
+
+// src/pipeline/sync.ts
 function assemblePackageRow(p) {
   const r = p.signals.registry;
   return {
@@ -2761,6 +2978,7 @@ var init_sync = __esm({
     init_cache();
     init_config();
     init_concurrency();
+    init_errors();
     init_http();
     init_logger();
     init_collect();
@@ -2771,18 +2989,20 @@ var init_sync = __esm({
     init_scoring();
     init_client();
     init_packages();
+    init_mineEdges();
     init_types();
   }
 });
 
 // src/pipeline/ingestQueue.ts
-function enqueueIngest(db, name) {
+function enqueueIngest(db, name, requestedByOwnerId = null) {
   if (queuedNames.has(name) || inFlight.has(name)) return;
   if (pending.length >= MAX_PENDING) {
     logger.warn(`ingest queue full (${MAX_PENDING}); dropping on-demand request for ${name}`);
     return;
   }
   queuedNames.add(name);
+  owners.set(name, requestedByOwnerId);
   pending.push(name);
   pump(db);
 }
@@ -2790,26 +3010,31 @@ function pump(db) {
   while (active < MAX_CONCURRENT && pending.length > 0) {
     const name = pending.shift();
     queuedNames.delete(name);
+    const owner = owners.get(name) ?? null;
+    owners.delete(name);
     inFlight.add(name);
     active += 1;
-    void ingestOne(db, name).finally(() => {
+    void runIngest(db, name, owner).finally(() => {
       inFlight.delete(name);
       active -= 1;
       pump(db);
     });
   }
 }
-async function ingestOne(db, name) {
+async function runIngest(db, name, requestedByOwnerId = null) {
   try {
-    const row = await syncOnePackage(db, name);
+    const row = await syncOnePackage(db, name, { requestedByOwnerId });
     if (row.confidence && row.confidence !== "unproven") {
-      await ensureSeedEntry(db, name, row.category);
+      await ensureSeedEntry(db, name, row.category).catch(() => {
+      });
     }
+    return row;
   } catch (err) {
     logger.warn(`on-demand ingest failed for ${name}: ${String(err)}`);
+    return null;
   }
 }
-var MAX_CONCURRENT, MAX_PENDING, pending, inFlight, queuedNames, active;
+var MAX_CONCURRENT, MAX_PENDING, pending, inFlight, queuedNames, owners, active;
 var init_ingestQueue = __esm({
   "src/pipeline/ingestQueue.ts"() {
     "use strict";
@@ -2822,20 +3047,24 @@ var init_ingestQueue = __esm({
     pending = [];
     inFlight = /* @__PURE__ */ new Set();
     queuedNames = /* @__PURE__ */ new Set();
+    owners = /* @__PURE__ */ new Map();
     active = 0;
   }
 });
 
 // src/pipeline/single.ts
-import { and as and3, eq as eq3, isNotNull as isNotNull2, sql as sql2 } from "drizzle-orm";
+import { and as and5, eq as eq6, isNotNull as isNotNull3, sql as sql4 } from "drizzle-orm";
+function raceTimeout(p, ms) {
+  return Promise.race([p, new Promise((resolve) => setTimeout(() => resolve(null), ms))]);
+}
 async function getSeedCategory(db, name) {
-  const [row] = await db.select({ category: seedPackages.category }).from(seedPackages).where(eq3(seedPackages.name, name)).limit(1);
+  const [row] = await db.select({ category: seedPackages.category }).from(seedPackages).where(eq6(seedPackages.name, name)).limit(1);
   return row?.category ?? null;
 }
 async function getCategoryMedianBundle(db, category) {
   const [row] = await db.select({
-    m: sql2`percentile_cont(0.5) within group (order by ${packages.bundleMinGzipKb})`
-  }).from(packages).where(and3(eq3(packages.category, category), isNotNull2(packages.bundleMinGzipKb)));
+    m: sql4`percentile_cont(0.5) within group (order by ${packages.bundleMinGzipKb})`
+  }).from(packages).where(and5(eq6(packages.category, category), isNotNull3(packages.bundleMinGzipKb)));
   return row?.m ?? null;
 }
 async function syncOnePackage(db, name, opts = {}) {
@@ -2898,20 +3127,31 @@ async function syncOnePackage(db, name, opts = {}) {
       now
     })
   );
+  if (!existing && opts.requestedByOwnerId) {
+    await stampFirstRequester(db, name, opts.requestedByOwnerId).catch(() => {
+    });
+  }
   await upsertPackageVersions(db, name, signals.registry?.versionTimeline ?? []).catch(
     () => {
     }
   );
+  await mineEdgesForPackage(db, name, signals.registry?.latestVersion ?? null, void 0, now);
   return await getPackageByName(db, name);
 }
-async function getOrFetchPackage(db, name) {
+async function getOrFetchPackage(db, name, opts = {}) {
   const existing = await getPackageByName(db, name);
   if (existing) return { row: existing, wasTracked: true, existsOnNpm: true };
   const exists = await npmPackageExists(name);
   if (!exists) return { row: null, wasTracked: false, existsOnNpm: false };
-  enqueueIngest(db, name);
+  if (opts.blockMs && opts.blockMs > 0) {
+    const row = await raceTimeout(runIngest(db, name, opts.requestedByOwnerId ?? null), opts.blockMs);
+    if (row) return { row, wasTracked: false, existsOnNpm: true };
+    return { row: null, wasTracked: false, existsOnNpm: true, queued: true };
+  }
+  enqueueIngest(db, name, opts.requestedByOwnerId ?? null);
   return { row: null, wasTracked: false, existsOnNpm: true, queued: true };
 }
+var FIRST_TOUCH_BUDGET_MS;
 var init_single = __esm({
   "src/pipeline/single.ts"() {
     "use strict";
@@ -2926,12 +3166,14 @@ var init_single = __esm({
     init_packages();
     init_schema();
     init_sync();
+    init_mineEdges();
     init_ingestQueue();
+    FIRST_TOUCH_BUDGET_MS = 4e3;
   }
 });
 
 // src/search/recommend.ts
-import { and as and4, cosineDistance, eq as eq4, isNotNull as isNotNull3, lte, sql as sql3 } from "drizzle-orm";
+import { and as and6, cosineDistance, eq as eq7, inArray as inArray2, isNotNull as isNotNull4, lte, sql as sql5 } from "drizzle-orm";
 async function recommend(db, opts, provider = createEmbeddingProvider()) {
   const limit = Math.min(Math.max(opts.limit ?? 3, 1), 5);
   const [queryVec] = await provider.embed([opts.need]);
@@ -2975,8 +3217,8 @@ function rrfFuse(lists, k = RRF_K) {
 }
 function buildConditions(constraints, category) {
   const conditions = [];
-  if (category) conditions.push(eq4(packages.category, category));
-  if (constraints?.license) conditions.push(eq4(packages.license, constraints.license));
+  if (category) conditions.push(eq7(packages.category, category));
+  if (constraints?.license) conditions.push(eq7(packages.license, constraints.license));
   if (constraints?.maxBundleKb !== void 0) {
     conditions.push(lte(packages.bundleMinGzipKb, constraints.maxBundleKb));
   }
@@ -2984,26 +3226,24 @@ function buildConditions(constraints, category) {
     const allowed = ["proven", "emerging", "promising", "unproven"].filter(
       (c) => CONFIDENCE_RANK[c] >= CONFIDENCE_RANK[constraints.minConfidence]
     );
-    conditions.push(
-      sql3`${packages.confidence} in ${sql3.raw(`(${allowed.map((c) => `'${c}'`).join(",")})`)}`
-    );
+    conditions.push(inArray2(packages.confidence, allowed));
   }
   return conditions;
 }
 async function runVectorQuery(db, queryVec, providerId, constraints, category, pool) {
   const distance = cosineDistance(packages.embedding, queryVec);
   const conditions = [
-    isNotNull3(packages.embedding),
-    eq4(packages.embeddingProvider, providerId),
+    isNotNull4(packages.embedding),
+    eq7(packages.embeddingProvider, providerId),
     ...buildConditions(constraints, category)
   ];
-  return db.select(ROW_COLUMNS).from(packages).where(and4(...conditions)).orderBy(distance).limit(pool);
+  return db.select(ROW_COLUMNS).from(packages).where(and6(...conditions)).orderBy(distance).limit(pool);
 }
 async function runLexicalQuery(db, need, constraints, category, pool) {
-  const tsquery = sql3`websearch_to_tsquery('english', ${need})`;
-  const rank = sql3`ts_rank(${packages.searchVector}, ${tsquery})`;
-  const conditions = [sql3`${packages.searchVector} @@ ${tsquery}`, ...buildConditions(constraints, category)];
-  return db.select(ROW_COLUMNS).from(packages).where(and4(...conditions)).orderBy(sql3`${rank} desc`).limit(pool);
+  const tsquery = sql5`websearch_to_tsquery('english', ${need})`;
+  const rank = sql5`ts_rank(${packages.searchVector}, ${tsquery})`;
+  const conditions = [sql5`${packages.searchVector} @@ ${tsquery}`, ...buildConditions(constraints, category)];
+  return db.select(ROW_COLUMNS).from(packages).where(and6(...conditions)).orderBy(sql5`${rank} desc`).limit(pool);
 }
 function toCandidate(row) {
   return {
@@ -3360,12 +3600,13 @@ __export(handlers_exports, {
   handleEvaluate: () => handleEvaluate,
   handleRecommend: () => handleRecommend,
   handleReportOutcome: () => handleReportOutcome,
+  handleUsage: () => handleUsage,
   handleVerify: () => handleVerify,
   latestDataAsOf: () => latestDataAsOf,
   rowToEvaluate: () => rowToEvaluate
 });
 import { createHash as createHash3 } from "crypto";
-import { sql as sql4 } from "drizzle-orm";
+import { sql as sql6 } from "drizzle-orm";
 function isStale(dataAsOf) {
   if (!dataAsOf) return true;
   return Date.now() - dataAsOf.getTime() > STALENESS_DAYS * DAY_MS2;
@@ -3374,8 +3615,8 @@ 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_MS2 : false;
+function withinDays(date2, days) {
+  return date2 ? Date.now() - date2.getTime() <= days * DAY_MS2 : false;
 }
 function topAdvisories(advisories, max = 5) {
   if (!advisories?.length) return [];
@@ -3414,7 +3655,7 @@ function rowToEvaluate(row) {
   };
 }
 async function latestDataAsOf(db) {
-  const [row] = await db.select({ m: sql4`max(${packages.dataAsOf})` }).from(packages);
+  const [row] = await db.select({ m: sql6`max(${packages.dataAsOf})` }).from(packages);
   return new Date(row?.m ?? Date.now()).toISOString();
 }
 function cacheKey(parts) {
@@ -3437,12 +3678,15 @@ async function handleRecommend(db, input) {
     { skipCache: (r) => r.candidates.length === 0 }
   );
 }
-async function handleEvaluate(db, input) {
+async function handleEvaluate(db, input, ownerId = null) {
   const out = await cached2(
     "eval",
     cacheKey([input.package]),
     async () => {
-      const { row, existsOnNpm } = await getOrFetchPackage(db, input.package);
+      const { row, existsOnNpm } = await getOrFetchPackage(db, input.package, {
+        blockMs: FIRST_TOUCH_BUDGET_MS,
+        requestedByOwnerId: ownerId
+      });
       if (!row) {
         return {
           tracked: false,
@@ -3458,12 +3702,14 @@ async function handleEvaluate(db, input) {
   );
   return "tracked" in out ? out : refreshStale(out);
 }
-async function handleCompare(db, input) {
+async function handleCompare(db, input, ownerId = null) {
   const out = await cached2(
     "cmp",
     cacheKey(input.packages),
     async () => {
-      const results = await Promise.all(input.packages.map((name) => getOrFetchPackage(db, name)));
+      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(rowToEvaluate).sort((a, b) => b.healthScore - a.healthScore);
       const missing = input.packages.filter((name) => !rows.some((r) => r.name === name));
       return {
@@ -3491,9 +3737,12 @@ function toBuildVerified(v) {
   };
 }
 async function handleCompat(db, input) {
-  return checkCompat(db, input.packages);
+  return checkCompat(db, input.packages, {
+    versions: input.versions,
+    node: input.node
+  });
 }
-async function handleVerify(db, input) {
+async function handleVerify(db, input, ownerId = null) {
   const name = input.package;
   const exists = await npmPackageExists(name);
   if (!exists) {
@@ -3514,7 +3763,9 @@ async function handleVerify(db, input) {
   }
   const [registry, { row, wasTracked }, popular] = await Promise.all([
     fetchNpmRegistry(name).catch(() => null),
-    getOrFetchPackage(db, name),
+    // 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);
@@ -3559,6 +3810,38 @@ async function handleVerify(db, input) {
     advisoryCount
   };
 }
+async function resolveVersion(db, name, requested) {
+  if (requested) return requested;
+  const row = await getPackageByName(db, name);
+  if (row?.latestVersion) return row.latestVersion;
+  const reg = await fetchNpmRegistry(name).catch(() => null);
+  return reg?.latestVersion ?? null;
+}
+async function handleUsage(db, input) {
+  const version = await resolveVersion(db, input.package, input.version);
+  if (!version) {
+    return {
+      package: input.package,
+      version: null,
+      surface: null,
+      available: false,
+      note: `Could not resolve a version for "${input.package}" on npm.`
+    };
+  }
+  const surface = await getStoredSurface(db, input.package, version);
+  const out = {
+    package: input.package,
+    version,
+    surface,
+    available: surface !== null,
+    note: surface ? void 0 : "No extracted API surface for this version yet; fall back to the README."
+  };
+  if (input.knownVersion && input.knownVersion !== version && surface) {
+    const known = await getStoredSurface(db, input.package, input.knownVersion);
+    if (known) out.delta = { ...diffSurface(known, surface), fromVersion: input.knownVersion };
+  }
+  return out;
+}
 async function handleReportOutcome(db, input, ownerId = null) {
   await recordOutcome(db, {
     ownerId,
@@ -3578,6 +3861,8 @@ var init_handlers = __esm({
     init_constants();
     init_check();
     init_packages();
+    init_apiSurfaces();
+    init_diff();
     init_verification();
     init_outcomes();
     init_successors2();
@@ -3601,7 +3886,7 @@ var init_handlers = __esm({
 });
 
 // src/mcp/diagram.ts
-import { inArray as inArray2 } from "drizzle-orm";
+import { inArray as inArray3 } from "drizzle-orm";
 function layerFor(item) {
   if (!item.category) return UNCLASSIFIED;
   if (item.category === "framework" && BACKEND_FRAMEWORKS.has(item.label)) return "Backend";
@@ -3654,7 +3939,7 @@ async function handleDiagram(db, input) {
       note: "Provide a `stack` of package names to diagram. lurq labels a stack you choose; it does not infer an architecture from a description."
     };
   }
-  const rows = await db.select({ name: packages.name, category: packages.category }).from(packages).where(inArray2(packages.name, input.stack));
+  const rows = await db.select({ name: packages.name, category: packages.category }).from(packages).where(inArray3(packages.name, input.stack));
   const known = new Map(rows.map((r) => [r.name, r.category]));
   const items = input.stack.map((name) => ({
     label: name,
@@ -3793,7 +4078,7 @@ __export(plan_exports, {
   resolvePins: () => resolvePins
 });
 import { createHash as createHash4 } from "crypto";
-import { inArray as inArray3 } from "drizzle-orm";
+import { inArray as inArray4 } from "drizzle-orm";
 function packageToCandidate(row) {
   return {
     name: row.name,
@@ -3808,12 +4093,12 @@ function packageToCandidate(row) {
     repoUrl: row.repoUrl
   };
 }
-async function resolvePins(db, using, recommendedNames) {
+async function resolvePins(db, using, recommendedNames, requestedByOwnerId = null) {
   const slots = [];
   const unresolved = [];
   for (const name of new Set(using ?? [])) {
     if (recommendedNames.has(name)) continue;
-    const { row } = await getOrFetchPackage(db, name);
+    const { row } = await getOrFetchPackage(db, name, { requestedByOwnerId });
     if (!row) {
       unresolved.push(name);
       continue;
@@ -3830,7 +4115,7 @@ async function resolvePins(db, using, recommendedNames) {
   }
   return { slots, unresolved };
 }
-async function handlePlan(db, input) {
+async function handlePlan(db, input, ownerId = null) {
   const optimize = input.optimize ?? "balanced";
   const decomposed = input.needs?.length ? { needs: dedupeNeeds(input.needs), source: "needs" } : input.document?.trim() ? await decompose(input.document) : null;
   const hasPins = Boolean(input.using?.length);
@@ -3885,7 +4170,8 @@ async function handlePlan(db, input) {
   const { slots: pinnedSlots, unresolved: unresolvedPins } = await resolvePins(
     db,
     input.using,
-    recommendedNames
+    recommendedNames,
+    ownerId
   );
   const slots = [...pinnedSlots, ...recSlots];
   const compatibility = await resolveCompat(db, slots);
@@ -4010,7 +4296,7 @@ function orderCandidates(cands, anchorFamily, optimize, bundleByName) {
 async function bundleSizes(db, candidates) {
   const names = [...new Set(candidates.map((c) => c.name))];
   if (names.length === 0) return /* @__PURE__ */ new Map();
-  const rows = await db.select({ name: packages.name, bundle: packages.bundleMinGzipKb }).from(packages).where(inArray3(packages.name, names));
+  const rows = await db.select({ name: packages.name, bundle: packages.bundleMinGzipKb }).from(packages).where(inArray4(packages.name, names));
   return new Map(rows.filter((r) => r.bundle != null).map((r) => [r.name, r.bundle]));
 }
 async function decompose(document) {
@@ -4190,10 +4476,61 @@ var init_compact = __esm({
   }
 });
 
-// src/mcp/server.ts
-var server_exports = {};
-__export(server_exports, {
-  buildMcpServer: () => buildMcpServer,
+// src/db/usage.ts
+import { and as and7, desc as desc4, eq as eq8, gte, sql as sql7 } from "drizzle-orm";
+function windowStart(days) {
+  return sql7`CURRENT_DATE - (${days}::int - 1)`;
+}
+async function recordUsage(db, ownerId, tool) {
+  if (!ownerId) return;
+  try {
+    await db.insert(ownerUsageDaily).values({ ownerId, date: sql7`CURRENT_DATE`, tool, count: 1 }).onConflictDoUpdate({
+      target: [ownerUsageDaily.ownerId, ownerUsageDaily.date, ownerUsageDaily.tool],
+      set: { count: sql7`${ownerUsageDaily.count} + 1` }
+    });
+  } catch {
+  }
+}
+async function getUsageSummary(db, ownerId, days) {
+  const rows = await db.execute(sql7`
+    select
+      to_char(d, 'YYYY-MM-DD') as date,
+      coalesce(sum(u.count), 0)::int as count
+    from generate_series(${windowStart(days)}, CURRENT_DATE, interval '1 day') as d
+    left join ${ownerUsageDaily} u
+      on u.date = d::date and u.owner_id = ${ownerId}
+    group by d
+    order by d
+  `);
+  const series = rows.map((r) => ({ date: String(r.date), count: Number(r.count) }));
+  const todayUtc = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const today = series.find((p) => p.date === todayUtc)?.count ?? 0;
+  return { today, series };
+}
+async function getUsageByTool(db, ownerId, days) {
+  const rows = await db.select({
+    tool: ownerUsageDaily.tool,
+    count: sql7`sum(${ownerUsageDaily.count})::int`
+  }).from(ownerUsageDaily).where(
+    and7(
+      eq8(ownerUsageDaily.ownerId, ownerId),
+      gte(ownerUsageDaily.date, windowStart(days))
+    )
+  ).groupBy(ownerUsageDaily.tool).orderBy(desc4(sql7`sum(${ownerUsageDaily.count})`));
+  return rows.map((r) => ({ tool: r.tool, count: Number(r.count) }));
+}
+var init_usage = __esm({
+  "src/db/usage.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_schema();
+  }
+});
+
+// src/mcp/server.ts
+var server_exports = {};
+__export(server_exports, {
+  buildMcpServer: () => buildMcpServer,
   npmName: () => npmName,
   startMcpServer: () => startMcpServer
 });
@@ -4205,6 +4542,13 @@ function json(obj) {
 }
 function buildMcpServer(db, ctx = {}) {
   const server = new McpServer({ name: SERVER_NAME, version: VERSION });
+  const run = (tool, fn) => (async () => {
+    try {
+      return await timed(tool, fn);
+    } finally {
+      void recordUsage(db, ctx.ownerId ?? null, tool);
+    }
+  })();
   server.registerTool(
     "recommend",
     {
@@ -4216,7 +4560,7 @@ function buildMcpServer(db, ctx = {}) {
         constraints: constraintsSchema
       }
     },
-    async (args) => json(await timed("recommend", () => handleRecommend(db, args)))
+    async (args) => json(await run("recommend", () => handleRecommend(db, args)))
   );
   server.registerTool(
     "evaluate",
@@ -4227,7 +4571,7 @@ function buildMcpServer(db, ctx = {}) {
         package: npmName.describe("npm package name")
       }
     },
-    async (args) => json(await timed("evaluate", () => handleEvaluate(db, args)))
+    async (args) => json(await run("evaluate", () => handleEvaluate(db, args, ctx.ownerId ?? null)))
   );
   server.registerTool(
     "compare",
@@ -4238,7 +4582,7 @@ function buildMcpServer(db, ctx = {}) {
         packages: z2.array(npmName).min(2).max(5).describe("2\u20135 npm package names")
       }
     },
-    async (args) => json(await timed("compare", () => handleCompare(db, args)))
+    async (args) => json(await run("compare", () => handleCompare(db, args, ctx.ownerId ?? null)))
   );
   server.registerTool(
     "compat",
@@ -4246,10 +4590,12 @@ function buildMcpServer(db, ctx = {}) {
       title: "Check package compatibility",
       description: "Check whether a set of packages forms a coherent stack: peer-dependency and engine-range compatibility across the whole set (instant, from declared metadata), plus any recorded sandbox-verified conflicts. Returns the exact clashing constraints. Read-only \u2014 does not run installs. Call before committing to a multi-package stack.",
       inputSchema: {
-        packages: z2.array(npmName).min(2).max(8).describe("2\u20138 npm package names to check together")
+        packages: z2.array(npmName).min(2).max(8).describe("2\u20138 npm package names to check together"),
+        versions: z2.record(z2.string()).optional().describe("Optional exact versions keyed by package name (use when not checking latest)"),
+        node: z2.string().optional().describe('Optional target Node runtime (e.g. "20" or "20.20.2") for engines.node checks')
       }
     },
-    async (args) => json(await timed("compat", () => handleCompat(db, args)))
+    async (args) => json(await run("compat", () => handleCompat(db, args)))
   );
   server.registerTool(
     "verify",
@@ -4260,7 +4606,20 @@ function buildMcpServer(db, ctx = {}) {
         package: npmName.describe("npm package name to verify")
       }
     },
-    async (args) => json(await timed("verify", () => handleVerify(db, args)))
+    async (args) => json(await run("verify", () => handleVerify(db, args, ctx.ownerId ?? null)))
+  );
+  server.registerTool(
+    "usage",
+    {
+      title: "Version-exact API surface + drift",
+      description: "Get a package version's real public API \u2014 the exported symbols and signatures extracted from its shipped .d.ts, exact to the version, none of it in the model's training data. Pass knownVersion (e.g. the version you were trained on) to get the precise delta: what was added, removed, renamed, or changed. Use before writing code against a package whose API may have moved. For framework file/convention changes (not exported symbols), consult the official migration guide / Context7 instead.",
+      inputSchema: {
+        package: npmName.describe("npm package name"),
+        version: z2.string().optional().describe("Target version (defaults to latest)"),
+        knownVersion: z2.string().optional().describe("A version you already know; returns the API delta from it to the target")
+      }
+    },
+    async (args) => json(await run("usage", () => handleUsage(db, args)))
   );
   server.registerTool(
     "diagram",
@@ -4271,7 +4630,7 @@ function buildMcpServer(db, ctx = {}) {
         stack: z2.array(npmName).optional().describe("Package names that make up the stack; omit or empty to get usage guidance")
       }
     },
-    async (args) => json(await timed("diagram", () => handleDiagram(db, args)))
+    async (args) => json(await run("diagram", () => handleDiagram(db, args)))
   );
   server.registerTool(
     "plan",
@@ -4292,7 +4651,7 @@ function buildMcpServer(db, ctx = {}) {
         optimize: z2.enum(["speed", "balanced"]).optional().describe("'speed' prefers the lightest-bundle option per slot; default 'balanced'")
       }
     },
-    async (args) => json(await timed("plan", () => handlePlan(db, args)))
+    async (args) => json(await run("plan", () => handlePlan(db, args, ctx.ownerId ?? null)))
   );
   server.registerTool(
     "report_outcome",
@@ -4308,7 +4667,7 @@ function buildMcpServer(db, ctx = {}) {
     },
     // ownerId comes from the authenticated key (ctx), NOT the tool arguments —
     // a caller must never be able to attribute an outcome to another org.
-    async (args) => json(await timed("report_outcome", () => handleReportOutcome(db, args, ctx.ownerId ?? null)))
+    async (args) => json(await run("report_outcome", () => handleReportOutcome(db, args, ctx.ownerId ?? null)))
   );
   return server;
 }
@@ -4342,6 +4701,7 @@ var init_server = __esm({
     init_plan();
     init_metrics();
     init_compact();
+    init_usage();
     categoryEnum = z2.enum(CATEGORIES);
     confidenceEnum = z2.enum(["proven", "emerging", "promising", "unproven"]);
     npmName = z2.string().trim().min(1).max(214).regex(/^(?:@[a-z0-9-][a-z0-9-._]*\/)?[a-z0-9-][a-z0-9-._]*$/i, "Invalid npm package name");
@@ -4356,7 +4716,7 @@ var init_server = __esm({
 
 // src/auth/apiKeys.ts
 import { createHash as createHash5, randomBytes } from "crypto";
-import { and as and5, desc as desc3, eq as eq5, isNull } from "drizzle-orm";
+import { and as and8, desc as desc5, eq as eq9, isNull as isNull3 } from "drizzle-orm";
 function hashKey(key) {
   return createHash5("sha256").update(key).digest("hex");
 }
@@ -4379,7 +4739,7 @@ async function createKey(db, input = {}) {
 function stampLastUsed(db, entry, now) {
   if (now - entry.lastStampAt < STAMP_INTERVAL_MS) return;
   entry.lastStampAt = now;
-  db.update(apiKeys).set({ lastUsedAt: new Date(now) }).where(eq5(apiKeys.id, entry.row.id)).then(void 0, (err) => logger.debug(`lastUsedAt stamp failed: ${String(err)}`));
+  db.update(apiKeys).set({ lastUsedAt: new Date(now) }).where(eq9(apiKeys.id, entry.row.id)).then(void 0, (err) => logger.debug(`lastUsedAt stamp failed: ${String(err)}`));
 }
 async function lookupActiveKey(db, key) {
   const hash = hashKey(key);
@@ -4389,7 +4749,7 @@ async function lookupActiveKey(db, key) {
     stampLastUsed(db, cached3, now);
     return cached3.row;
   }
-  const [row] = await db.select().from(apiKeys).where(and5(eq5(apiKeys.keyHash, hash), isNull(apiKeys.revokedAt))).limit(1);
+  const [row] = await db.select().from(apiKeys).where(and8(eq9(apiKeys.keyHash, hash), isNull3(apiKeys.revokedAt))).limit(1);
   if (!row) {
     authCache.delete(hash);
     return null;
@@ -4399,26 +4759,31 @@ async function lookupActiveKey(db, key) {
   stampLastUsed(db, entry, now);
   return row;
 }
-async function listKeys(db) {
-  return db.select().from(apiKeys).orderBy(desc3(apiKeys.createdAt));
+async function listKeysForOwner(db, ownerId) {
+  return db.select().from(apiKeys).where(eq9(apiKeys.ownerId, ownerId)).orderBy(desc5(apiKeys.createdAt));
 }
 function matchByPrefixOrId(prefixOrId) {
   const asId = Number(prefixOrId);
-  return Number.isInteger(asId) && String(asId) === prefixOrId.trim() ? eq5(apiKeys.id, asId) : eq5(apiKeys.prefix, prefixOrId);
+  return Number.isInteger(asId) && String(asId) === prefixOrId.trim() ? eq9(apiKeys.id, asId) : eq9(apiKeys.prefix, prefixOrId);
+}
+async function findKeyForOwner(db, args) {
+  const [row] = await db.select().from(apiKeys).where(and8(matchByPrefixOrId(args.prefixOrId), isNull3(apiKeys.revokedAt))).limit(1);
+  if (!row || row.ownerId !== args.ownerId) return null;
+  return row;
 }
 async function revokeKey(db, prefixOrId) {
-  const rows = await db.update(apiKeys).set({ revokedAt: /* @__PURE__ */ new Date() }).where(and5(matchByPrefixOrId(prefixOrId), isNull(apiKeys.revokedAt))).returning({ id: apiKeys.id });
+  const rows = await db.update(apiKeys).set({ revokedAt: /* @__PURE__ */ new Date() }).where(and8(matchByPrefixOrId(prefixOrId), isNull3(apiKeys.revokedAt))).returning({ id: apiKeys.id });
   return rows.length;
 }
 async function rotateKey(db, prefixOrId) {
-  const [previous] = await db.select().from(apiKeys).where(and5(matchByPrefixOrId(prefixOrId), isNull(apiKeys.revokedAt))).limit(1);
+  const [previous] = await db.select().from(apiKeys).where(and8(matchByPrefixOrId(prefixOrId), isNull3(apiKeys.revokedAt))).limit(1);
   if (!previous) return null;
   const { key, row } = await createKey(db, {
     label: previous.label ?? void 0,
     tier: previous.tier,
     ownerId: previous.ownerId ?? void 0
   });
-  await db.update(apiKeys).set({ revokedAt: /* @__PURE__ */ new Date() }).where(eq5(apiKeys.id, previous.id));
+  await db.update(apiKeys).set({ revokedAt: /* @__PURE__ */ new Date() }).where(eq9(apiKeys.id, previous.id));
   return { key, row, previous };
 }
 var DISPLAY_BODY, authCache, AUTH_TTL_MS, STAMP_INTERVAL_MS;
@@ -4542,7 +4907,7 @@ async function startHttpServer(opts = {}) {
     ...makeStore ? { store: makeStore("rl:key:") } : {},
     message: rpcError(-32029, "Rate limit exceeded.")
   });
-  app.post("/keys", async (req, res) => {
+  const requireIssuerSecret = (req, res, next) => {
     const secret = config.LURQ_ISSUER_SECRET;
     if (!secret) {
       res.status(404).end();
@@ -4554,6 +4919,18 @@ async function startHttpServer(opts = {}) {
       res.status(401).json({ error: "Invalid issuer secret." });
       return;
     }
+    next();
+  };
+  const toDashboardKey = (row) => ({
+    id: row.id,
+    prefix: row.prefix,
+    label: row.label,
+    tier: row.tier,
+    createdAt: row.createdAt,
+    lastUsedAt: row.lastUsedAt,
+    revokedAt: row.revokedAt
+  });
+  app.post("/keys", requireIssuerSecret, async (req, res) => {
     const body = req.body ?? {};
     const ownerId = typeof body.ownerId === "string" ? body.ownerId.trim() : "";
     if (!ownerId) {
@@ -4569,6 +4946,127 @@ async function startHttpServer(opts = {}) {
       res.status(500).json({ error: "Could not issue key." });
     }
   });
+  app.get("/keys", requireIssuerSecret, async (req, res) => {
+    const ownerId = typeof req.query.ownerId === "string" ? req.query.ownerId.trim() : "";
+    if (!ownerId) {
+      res.status(400).json({ error: "ownerId is required." });
+      return;
+    }
+    try {
+      const rows = await listKeysForOwner(db, ownerId);
+      res.status(200).json({ keys: rows.map(toDashboardKey) });
+    } catch (err) {
+      logger.error("key listing failed:", err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: "Could not list keys." });
+    }
+  });
+  app.post("/keys/:prefix/revoke", requireIssuerSecret, async (req, res) => {
+    const prefix = req.params.prefix;
+    const body = req.body ?? {};
+    const ownerId = typeof body.ownerId === "string" ? body.ownerId.trim() : "";
+    if (typeof prefix !== "string" || !ownerId) {
+      res.status(400).json({ error: "ownerId is required." });
+      return;
+    }
+    try {
+      const row = await findKeyForOwner(db, { prefixOrId: prefix, ownerId });
+      if (!row) {
+        res.status(404).json({ error: "Key not found." });
+        return;
+      }
+      await revokeKey(db, String(row.id));
+      res.status(200).json({ revoked: true });
+    } catch (err) {
+      logger.error("key revoke failed:", err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: "Could not revoke key." });
+    }
+  });
+  app.post("/keys/:prefix/rotate", requireIssuerSecret, async (req, res) => {
+    const prefix = req.params.prefix;
+    const body = req.body ?? {};
+    const ownerId = typeof body.ownerId === "string" ? body.ownerId.trim() : "";
+    if (typeof prefix !== "string" || !ownerId) {
+      res.status(400).json({ error: "ownerId is required." });
+      return;
+    }
+    try {
+      const row = await findKeyForOwner(db, { prefixOrId: prefix, ownerId });
+      if (!row) {
+        res.status(404).json({ error: "Key not found." });
+        return;
+      }
+      const rotated = await rotateKey(db, String(row.id));
+      if (!rotated) {
+        res.status(404).json({ error: "Key not found." });
+        return;
+      }
+      res.status(200).json({ key: rotated.key, prefix: rotated.row.prefix });
+    } catch (err) {
+      logger.error("key rotate failed:", err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: "Could not rotate key." });
+    }
+  });
+  app.get("/outcomes", requireIssuerSecret, async (req, res) => {
+    const ownerId = typeof req.query.ownerId === "string" ? req.query.ownerId.trim() : "";
+    if (!ownerId) {
+      res.status(400).json({ error: "ownerId is required." });
+      return;
+    }
+    const limitRaw = typeof req.query.limit === "string" ? Number(req.query.limit) : void 0;
+    const limit = limitRaw && Number.isInteger(limitRaw) && limitRaw > 0 ? Math.min(limitRaw, 200) : void 0;
+    try {
+      const rows = await getOutcomesByOwner(db, ownerId, { limit });
+      res.status(200).json({
+        outcomes: rows.map((row) => ({
+          packageName: row.packageName,
+          accepted: row.accepted,
+          buildSignal: row.buildSignal,
+          need: row.need,
+          createdAt: row.createdAt
+        }))
+      });
+    } catch (err) {
+      logger.error("outcomes read failed:", err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: "Could not read outcomes." });
+    }
+  });
+  app.get("/usage", requireIssuerSecret, async (req, res) => {
+    const ownerId = typeof req.query.ownerId === "string" ? req.query.ownerId.trim() : "";
+    if (!ownerId) {
+      res.status(400).json({ error: "ownerId is required." });
+      return;
+    }
+    const daysRaw = typeof req.query.days === "string" ? Number(req.query.days) : NaN;
+    const days = Number.isInteger(daysRaw) && daysRaw > 0 ? Math.min(daysRaw, 365) : 30;
+    try {
+      const [summary, byTool] = await Promise.all([
+        getUsageSummary(db, ownerId, days),
+        getUsageByTool(db, ownerId, days)
+      ]);
+      res.status(200).json({ today: summary.today, series: summary.series, byTool });
+    } catch (err) {
+      logger.error("usage read failed:", err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: "Could not read usage." });
+    }
+  });
+  app.get("/contributions", requireIssuerSecret, async (req, res) => {
+    const ownerId = typeof req.query.ownerId === "string" ? req.query.ownerId.trim() : "";
+    if (!ownerId) {
+      res.status(400).json({ error: "ownerId is required." });
+      return;
+    }
+    const limitRaw = typeof req.query.limit === "string" ? Number(req.query.limit) : NaN;
+    const limit = Number.isInteger(limitRaw) && limitRaw > 0 ? Math.min(limitRaw, 200) : 50;
+    const offsetRaw = typeof req.query.offset === "string" ? Number(req.query.offset) : NaN;
+    const offset = Number.isInteger(offsetRaw) && offsetRaw > 0 ? offsetRaw : 0;
+    try {
+      const { total, packages: rows } = await getContributionsByOwner(db, ownerId, { limit, offset });
+      res.status(200).json({ total, packages: rows });
+    } catch (err) {
+      logger.error("contributions read failed:", err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: "Could not read contributions." });
+    }
+  });
   app.post("/mcp", ipLimiter, auth, keyLimiter, async (req, res) => {
     const server = buildMcpServer(db, { ownerId: req.lurqKey?.ownerId ?? null });
     const transport = new StreamableHTTPServerTransport({
@@ -4601,236 +5099,15 @@ var init_http2 = __esm({
     init_config();
     init_logger();
     init_apiKeys();
+    init_outcomes();
+    init_packages();
+    init_usage();
     init_client();
     init_server();
     init_metrics();
   }
 });
 
-// src/pipeline/rescore.ts
-import { isNotNull as isNotNull4 } from "drizzle-orm";
-import { eq as eq6 } from "drizzle-orm";
-async function runRescore() {
-  const weights = loadWeights();
-  const handle = createDb({ max: 4 });
-  try {
-    const rows = await handle.db.select({ id: packages.id, breakdown: packages.scoreBreakdown, healthScore: packages.healthScore }).from(packages).where(isNotNull4(packages.scoreBreakdown));
-    let updated = 0;
-    for (const row of rows) {
-      if (!row.breakdown) continue;
-      const health = computeHealthScore(row.breakdown, weights.health);
-      if (health !== row.healthScore) {
-        await handle.db.update(packages).set({ healthScore: health, updatedAt: /* @__PURE__ */ new Date() }).where(eq6(packages.id, row.id));
-        updated++;
-      }
-    }
-    logger.info(`Rescored ${rows.length} package(s); ${updated} health score(s) changed.`);
-    if (updated > 0) await invalidateCache();
-    return { seen: rows.length, updated };
-  } finally {
-    await handle.close();
-  }
-}
-var init_rescore = __esm({
-  "src/pipeline/rescore.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_cache();
-    init_logger();
-    init_client();
-    init_schema();
-    init_scoring();
-    init_weights();
-  }
-});
-
-// src/db/discovery.ts
-import { eq as eq7 } from "drizzle-orm";
-async function getKnownNames(db) {
-  const [tracked, queued] = await Promise.all([
-    db.select({ name: packages.name }).from(packages),
-    db.select({ name: discoveryQueue.name }).from(discoveryQueue)
-  ]);
-  return /* @__PURE__ */ new Set([...tracked.map((r) => r.name), ...queued.map((r) => r.name)]);
-}
-async function enqueueCandidates(db, candidates) {
-  if (candidates.length === 0) return 0;
-  const rows = candidates.map((c) => ({ name: c.name, discoveredVia: c.via }));
-  const inserted = await db.insert(discoveryQueue).values(rows).onConflictDoNothing({ target: discoveryQueue.name }).returning({ id: discoveryQueue.id });
-  return inserted.length;
-}
-async function getPendingCandidates(db, limit) {
-  return db.select().from(discoveryQueue).where(eq7(discoveryQueue.status, "pending")).limit(limit);
-}
-async function setDiscoveryStatus(db, name, data) {
-  await db.update(discoveryQueue).set({ status: data.status, ...data.preScore !== void 0 ? { preScore: data.preScore } : {} }).where(eq7(discoveryQueue.name, name));
-}
-var init_discovery = __esm({
-  "src/db/discovery.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_schema();
-  }
-});
-
-// src/pipeline/discovery.ts
-import { isNotNull as isNotNull5 } from "drizzle-orm";
-function selectCandidates(raw, known) {
-  const seen = new Set(known);
-  const out = [];
-  for (const c of raw) {
-    const name = c.name?.trim();
-    if (!name || seen.has(name)) continue;
-    seen.add(name);
-    out.push({ name, via: c.via });
-  }
-  return out;
-}
-function passesGate(preScore) {
-  return preScore !== null && preScore >= DISCOVERY.minPreScore;
-}
-async function preScorePackage(name, fetchImpl) {
-  try {
-    const registry = await fetchNpmRegistry(name, fetchImpl);
-    const signals = {
-      name,
-      registry,
-      downloads: null,
-      github: null,
-      depsDev: null,
-      bundle: null,
-      errors: []
-    };
-    return computeQuality(toScoringInput(signals, null));
-  } catch {
-    return null;
-  }
-}
-async function graphChannel(db) {
-  const tracked = await db.select({ name: packages.name, version: packages.latestVersion }).from(packages).where(isNotNull5(packages.latestVersion));
-  const out = [];
-  for (const t of tracked) {
-    if (!t.version) continue;
-    const deps = (await fetchDependencyNames(t.name, t.version)).slice(
-      0,
-      DISCOVERY.graphNeighborsPerSeed
-    );
-    for (const name of deps) out.push({ name, via: "dependency-graph" });
-  }
-  return out;
-}
-async function searchChannel() {
-  const out = [];
-  for (const category of CATEGORIES) {
-    if (category === "other") continue;
-    const hits = await searchNpm(`keywords:${category}`, DISCOVERY.searchSizePerCategory);
-    for (const hit of hits) {
-      const via = isRecent(hit.date) ? "recent" : "category-search";
-      out.push({ name: hit.name, via });
-    }
-  }
-  return out;
-}
-function isRecent(date) {
-  if (!date) return false;
-  const ms = Date.parse(date);
-  if (Number.isNaN(ms)) return false;
-  return Date.now() - ms <= 90 * 24 * 60 * 60 * 1e3;
-}
-async function runDiscovery(opts = {}) {
-  const cap = opts.perRunCap ?? DISCOVERY.perRunCap;
-  const handle = createDb({ max: 6 });
-  try {
-    logger.info("Discovery: gathering candidates from graph + search channels\u2026");
-    const [graph, search] = await Promise.all([graphChannel(handle.db), searchChannel()]);
-    const known = await getKnownNames(handle.db);
-    const fresh = selectCandidates([...graph, ...search], known);
-    const enqueued = await enqueueCandidates(handle.db, fresh);
-    logger.info(
-      `Discovery: ${graph.length} graph + ${search.length} search candidates \u2192 ${enqueued} new queued.`
-    );
-    const pending2 = await getPendingCandidates(handle.db, cap * 4);
-    const scored = [];
-    for (const cand of pending2) {
-      if (cand.preScore !== null) {
-        scored.push({ name: cand.name, preScore: cand.preScore });
-        continue;
-      }
-      const preScore = await preScorePackage(cand.name);
-      await setDiscoveryStatus(handle.db, cand.name, {
-        status: passesGate(preScore) ? "pending" : "rejected",
-        preScore: preScore ?? null
-      });
-      if (passesGate(preScore)) scored.push({ name: cand.name, preScore });
-    }
-    logger.info(`Discovery: gated ${pending2.length}; ${scored.length} cleared the quality bar.`);
-    scored.sort((a, b) => b.preScore - a.preScore);
-    const toIngest = scored.slice(0, cap);
-    const deferred = scored.slice(cap);
-    if (deferred.length > 0) {
-      logger.info(
-        `Discovery: per-run cap ${cap} reached \u2014 ${deferred.length} eligible candidate(s) deferred to the next run: ${deferred.map((d) => d.name).join(", ")}`
-      );
-    }
-    let ingested = 0;
-    if (!opts.dryRun) {
-      for (const cand of toIngest) {
-        try {
-          await syncOnePackage(handle.db, cand.name);
-          await setDiscoveryStatus(handle.db, cand.name, { status: "ingested" });
-          ingested++;
-        } catch (err) {
-          logger.warn(`Discovery: failed to ingest ${cand.name}: ${err.message}`);
-        }
-      }
-    }
-    logger.info(`Discovery: ingested ${ingested}/${toIngest.length} candidate(s).`);
-    return {
-      enqueued,
-      gated: pending2.length,
-      passed: scored.length,
-      ingested,
-      droppedToNextRun: deferred.length
-    };
-  } finally {
-    await handle.close();
-  }
-}
-var init_discovery2 = __esm({
-  "src/pipeline/discovery.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_logger();
-    init_types();
-    init_client();
-    init_discovery();
-    init_schema();
-    init_depsDev();
-    init_npmRegistry();
-    init_npmSearch();
-    init_scoring();
-    init_weights();
-    init_single();
-  }
-});
-
-// src/pipeline/index.ts
-var pipeline_exports = {};
-__export(pipeline_exports, {
-  runDiscovery: () => runDiscovery,
-  runRescore: () => runRescore,
-  runSync: () => runSync
-});
-var init_pipeline = __esm({
-  "src/pipeline/index.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_sync();
-    init_rescore();
-    init_discovery2();
-  }
-});
-
 // src/cli/format.ts
 function table(headers, rows) {
   const widths = headers.map((h, i) => Math.max(width(h), ...rows.map((r) => width(r[i] ?? ""))));
@@ -4963,9 +5240,9 @@ var init_planView = __esm({
 });
 
 // src/db/watch.ts
-import { eq as eq8 } from "drizzle-orm";
+import { eq as eq10 } from "drizzle-orm";
 async function getWatchCursor(db, id) {
-  const rows = await db.select({ seq: watchState.seq }).from(watchState).where(eq8(watchState.id, id)).limit(1);
+  const rows = await db.select({ seq: watchState.seq }).from(watchState).where(eq10(watchState.id, id)).limit(1);
   return rows[0]?.seq ?? null;
 }
 async function setWatchCursor(db, id, seq) {
@@ -5130,7 +5407,7 @@ function stderrOf(err) {
   }
   return String(err);
 }
-var execFileAsync, INSTALL_TIMEOUT_MS, SMOKE_TIMEOUT_MS, ERROR_MAX, toSpec, LocalSandbox;
+var execFileAsync, INSTALL_TIMEOUT_MS, SMOKE_TIMEOUT_MS, ERROR_MAX, EXEC_MAX_BUFFER, toSpec, LocalSandbox;
 var init_local = __esm({
   "src/sandbox/local.ts"() {
     "use strict";
@@ -5140,6 +5417,7 @@ var init_local = __esm({
     INSTALL_TIMEOUT_MS = 12e4;
     SMOKE_TIMEOUT_MS = 3e4;
     ERROR_MAX = 500;
+    EXEC_MAX_BUFFER = 8 * 1024 * 1024;
     toSpec = (p) => p.version ? `${p.name}@${p.version}` : p.name;
     LocalSandbox = class {
       name = "local";
@@ -5161,7 +5439,8 @@ var init_local = __esm({
         const specs = packages2.map(toSpec);
         const dir = await mkdtemp(join3(tmpdir(), "lurq-sandbox-"));
         const started = Date.now();
-        const loaded = packages2.map((p) => ({ name: p.name, loaded: null }));
+        const smokeTargets = opts.smokePackages ?? packages2;
+        const loaded = smokeTargets.map((p) => ({ name: p.name, loaded: null }));
         let installed = false;
         let error = null;
         try {
@@ -5175,9 +5454,9 @@ var init_local = __esm({
             signal: opts.signal
           });
           installed = true;
-          for (let i = 0; i < packages2.length; i++) {
+          for (let i = 0; i < smokeTargets.length; i++) {
             try {
-              await execFileAsync("node", smokeScript(packages2[i].name, target.moduleSystem), {
+              await execFileAsync("node", smokeScript(smokeTargets[i].name, target.moduleSystem), {
                 cwd: dir,
                 timeout: SMOKE_TIMEOUT_MS,
                 signal: opts.signal
@@ -5203,6 +5482,54 @@ var init_local = __esm({
           error
         };
       }
+      async exec(command, opts = {}) {
+        const dir = await mkdtemp(join3(tmpdir(), "lurq-exec-"));
+        try {
+          await writeFile2(
+            join3(dir, "package.json"),
+            JSON.stringify({ name: "lurq-sandbox", version: "0.0.0", private: true })
+          );
+          if (opts.install?.length) {
+            await execFileAsync(
+              "npm",
+              npmInstallArgs(opts.install.map(toSpec), { allowScripts: opts.allowScripts ?? false }),
+              { cwd: dir, timeout: opts.timeoutMs ?? INSTALL_TIMEOUT_MS, signal: opts.signal }
+            );
+          }
+          const { stdout, stderr } = await execFileAsync("sh", ["-c", command], {
+            cwd: dir,
+            timeout: opts.timeoutMs ?? SMOKE_TIMEOUT_MS,
+            signal: opts.signal,
+            maxBuffer: EXEC_MAX_BUFFER
+          });
+          return { exitCode: 0, stdout, stderr };
+        } catch (err) {
+          const e = err;
+          if (typeof e?.code === "number") {
+            return {
+              exitCode: e.code,
+              stdout: typeof e.stdout === "string" ? e.stdout : "",
+              stderr: typeof e.stderr === "string" ? e.stderr : stderrOf(err)
+            };
+          }
+          throw err;
+        } finally {
+          await rm(dir, { recursive: true, force: true }).catch(() => {
+          });
+        }
+      }
+      async getRuntimeInfo() {
+        let nodeVersion = "unknown";
+        let npmVersion = "unknown";
+        try {
+          const nodeOut = await execFileAsync("node", ["--version"]);
+          nodeVersion = nodeOut.stdout.trim() || "unknown";
+          const npmOut = await execFileAsync("npm", ["--version"]);
+          npmVersion = npmOut.stdout.trim() || "unknown";
+        } catch {
+        }
+        return { nodeVersion, npmVersion };
+      }
     };
   }
 });
@@ -5215,7 +5542,6 @@ __export(e2b_exports, {
   shQuote: () => shQuote,
   smokeCommand: () => smokeCommand
 });
-import Sandbox from "e2b";
 function shQuote(s) {
   return `'${s.replace(/'/g, `'\\''`)}'`;
 }
@@ -5275,10 +5601,12 @@ var init_e2b = __esm({
         const specs = packages2.map(toSpec2);
         const installTimeout = opts.timeoutMs ?? INSTALL_TIMEOUT_MS2;
         const started = Date.now();
-        const loaded = packages2.map((p) => ({ name: p.name, loaded: null }));
+        const smokeTargets = opts.smokePackages ?? packages2;
+        const loaded = smokeTargets.map((p) => ({ name: p.name, loaded: null }));
         let installed = false;
         let error = null;
         const install = installCommand(specs, allowScripts);
+        const { default: Sandbox } = await import("e2b");
         const createOpts = {
           apiKey: config.E2B_API_KEY,
           timeoutMs: installTimeout + SMOKE_TIMEOUT_MS2 * packages2.length + 3e4
@@ -5291,9 +5619,9 @@ var init_e2b = __esm({
           );
           await sandbox.commands.run(install, { cwd: WORKDIR, timeoutMs: installTimeout });
           installed = true;
-          for (let i = 0; i < packages2.length; i++) {
+          for (let i = 0; i < smokeTargets.length; i++) {
             try {
-              await sandbox.commands.run(smokeCommand(packages2[i].name, target.moduleSystem), {
+              await sandbox.commands.run(smokeCommand(smokeTargets[i].name, target.moduleSystem), {
                 cwd: WORKDIR,
                 timeoutMs: SMOKE_TIMEOUT_MS2
               });
@@ -5318,6 +5646,62 @@ var init_e2b = __esm({
           error
         };
       }
+      async exec(command, opts = {}) {
+        const config = getConfig();
+        const timeoutMs = opts.timeoutMs ?? SMOKE_TIMEOUT_MS2;
+        const install = opts.install?.length ? installCommand(opts.install.map(toSpec2), opts.allowScripts ?? false) : null;
+        const { default: Sandbox } = await import("e2b");
+        const createOpts = {
+          apiKey: config.E2B_API_KEY,
+          timeoutMs: (install ? INSTALL_TIMEOUT_MS2 : 0) + timeoutMs + 3e4
+        };
+        const sandbox = config.E2B_TEMPLATE ? await Sandbox.create(config.E2B_TEMPLATE, createOpts) : await Sandbox.create(createOpts);
+        try {
+          await sandbox.files.write(
+            `${WORKDIR}/package.json`,
+            JSON.stringify({ name: "lurq-sandbox", version: "0.0.0", private: true })
+          );
+          if (install) {
+            await sandbox.commands.run(install, { cwd: WORKDIR, timeoutMs: INSTALL_TIMEOUT_MS2 });
+          }
+          const out = await sandbox.commands.run(command, { cwd: WORKDIR, timeoutMs });
+          return { exitCode: out.exitCode ?? 0, stdout: out.stdout ?? "", stderr: out.stderr ?? "" };
+        } catch (err) {
+          const e = err;
+          if (typeof e?.exitCode === "number") {
+            return {
+              exitCode: e.exitCode,
+              stdout: typeof e.stdout === "string" ? e.stdout : "",
+              stderr: typeof e.stderr === "string" ? e.stderr : errText(err)
+            };
+          }
+          throw err;
+        } finally {
+          await sandbox.kill().catch(() => {
+          });
+        }
+      }
+      async getRuntimeInfo() {
+        let nodeVersion = "unknown";
+        let npmVersion = "unknown";
+        const config = getConfig();
+        try {
+          const { default: Sandbox } = await import("e2b");
+          const createOpts = { apiKey: config.E2B_API_KEY, timeoutMs: 3e4 };
+          const sandbox = config.E2B_TEMPLATE ? await Sandbox.create(config.E2B_TEMPLATE, createOpts) : await Sandbox.create(createOpts);
+          try {
+            const nodeOut = await sandbox.commands.run("node --version");
+            nodeVersion = (nodeOut.stdout ?? "").trim() || "unknown";
+            const npmOut = await sandbox.commands.run("npm --version");
+            npmVersion = (npmOut.stdout ?? "").trim() || "unknown";
+          } finally {
+            await sandbox.kill().catch(() => {
+            });
+          }
+        } catch {
+        }
+        return { nodeVersion, npmVersion };
+      }
     };
   }
 });
@@ -5372,16 +5756,59 @@ var init_sandbox2 = __esm({
   }
 });
 
+// src/pipeline/resolveCheck.ts
+import { execFile as execFile2 } from "child_process";
+import { mkdtemp as mkdtemp2, rm as rm2, writeFile as writeFile3 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join4 } from "path";
+import { promisify as promisify2 } from "util";
+async function resolveSet(specs, opts = {}) {
+  const dir = await mkdtemp2(join4(tmpdir2(), "lurq-resolve-"));
+  try {
+    const dependencies = {};
+    for (const s of specs) dependencies[s.name] = s.version ?? "latest";
+    await writeFile3(
+      join4(dir, "package.json"),
+      JSON.stringify({ name: "lurq-resolve", private: true, dependencies })
+    );
+    await execFileP("npm", ["install", "--package-lock-only", "--no-audit", "--no-fund"], {
+      cwd: dir,
+      timeout: opts.timeoutMs ?? 6e4
+    });
+    return { resolved: true, reason: null };
+  } catch (err) {
+    const msg = err.stderr ?? err.message ?? "";
+    if (/ERESOLVE/i.test(msg)) return { resolved: false, reason: "ERESOLVE" };
+    throw err;
+  } finally {
+    await rm2(dir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+var execFileP;
+var init_resolveCheck = __esm({
+  "src/pipeline/resolveCheck.ts"() {
+    "use strict";
+    init_esm_shims();
+    execFileP = promisify2(execFile2);
+  }
+});
+
 // src/pipeline/compat.ts
 var compat_exports = {};
 __export(compat_exports, {
+  backfillVerify: () => backfillVerify,
   deriveCompatEdges: () => deriveCompatEdges,
+  drainCompatVerifyQueue: () => drainCompatVerifyQueue,
+  fullyCovered: () => fullyCovered,
+  pairKey: () => pairKey,
+  resolveBackfill: () => resolveBackfill,
+  resolveVerifyCompatibility: () => resolveVerifyCompatibility,
   verifyCompatibility: () => verifyCompatibility
 });
-function deriveCompatEdges(resolved, result) {
-  const allLoaded = result.loaded.every((l) => l.loaded === true);
+function pairwiseEdges(resolved, success) {
   const edges = [];
-  if (result.installed && allLoaded) {
+  if (success) {
     for (let i = 0; i < resolved.length; i++) {
       for (let j = i + 1; j < resolved.length; j++) {
         edges.push({
@@ -5404,6 +5831,9 @@ function deriveCompatEdges(resolved, result) {
   }
   return edges;
 }
+function deriveCompatEdges(resolved, result) {
+  return pairwiseEdges(resolved, result.installed && result.loaded.every((l) => l.loaded === true));
+}
 async function verifyCompatibility(db, packages2, opts = {}) {
   const resolved = await Promise.all(
     packages2.map(async (name) => ({
@@ -5416,6 +5846,12 @@ async function verifyCompatibility(db, packages2, opts = {}) {
     { allowScripts: opts.allowScripts }
   );
   const edges = deriveCompatEdges(resolved, result);
+  await persistCompatEdges(db, edges, "verified", result.driver);
+  const failed = !result.installed || !result.loaded.every((l) => l.loaded === true);
+  return { result, edges, unattributedConflict: failed && edges.length === 0 };
+}
+async function persistCompatEdges(db, edges, compatibleProvenance, driver) {
+  const now = /* @__PURE__ */ new Date();
   for (const e of edges) {
     const pair = canonicalPair(
       { name: e.a, version: e.aVersion },
@@ -5424,21 +5860,106 @@ async function verifyCompatibility(db, packages2, opts = {}) {
     await upsertCompatEdge(db, {
       ...pair,
       status: e.status,
-      driver: result.driver,
-      ranAt: /* @__PURE__ */ new Date()
+      provenance: e.status === "conflict" ? "conflict" : compatibleProvenance,
+      // Witness accrues for co-resolution evidence (`observed`); ignored otherwise.
+      witnessCount: e.status === "compatible" && compatibleProvenance === "observed" ? 1 : 0,
+      driver,
+      ranAt: now
     }).catch(() => {
     });
   }
-  const failed = !result.installed || !result.loaded.every((l) => l.loaded === true);
-  return { result, edges, unattributedConflict: failed && edges.length === 0 };
 }
+async function resolveVerifyCompatibility(db, packages2) {
+  const resolved = await Promise.all(
+    packages2.map(async (name) => ({
+      name,
+      version: (await getPackageByName(db, name))?.latestVersion ?? "latest"
+    }))
+  );
+  const res = await resolveSet(
+    resolved.map((r) => ({ name: r.name, version: r.version === "latest" ? null : r.version }))
+  );
+  const edges = pairwiseEdges(resolved, res.resolved);
+  await persistCompatEdges(db, edges, "observed", "npm-resolve");
+  return { edges, resolved: res.resolved };
+}
+async function coveredPairs(db, names) {
+  const edges = await getCompatEdges(db, names);
+  return new Set(edges.map((e) => pairKey(e.packageA, e.packageB)));
+}
+async function runBackfill(db, opts, runner, label) {
+  const topN = opts.topN ?? 50;
+  const batchSize = Math.max(2, opts.batchSize ?? 5);
+  const names = await getTopPackageNames(db, topN);
+  const covered = await coveredPairs(db, names);
+  let verified = 0;
+  let batches = 0;
+  let skipped = 0;
+  for (let i = 0; i < names.length; i += batchSize) {
+    const batch = names.slice(i, i + batchSize);
+    if (batch.length < 2) continue;
+    if (fullyCovered(batch, covered)) {
+      skipped++;
+      continue;
+    }
+    logger.info(`${label}: ${batch.join(", ")}`);
+    const { edges } = await runner(db, batch).catch((err) => {
+      logger.warn(`${label} batch failed (${batch.join(", ")}): ${String(err)}`);
+      return { edges: [] };
+    });
+    verified += edges.length;
+    batches++;
+  }
+  logger.info(`${label}: ${verified} edges across ${batches} runs, ${skipped} batches skipped`);
+  return { batches, verified, skipped };
+}
+async function backfillVerify(db, opts = {}) {
+  return runBackfill(db, opts, verifyCompatibility, "backfill(sandbox)");
+}
+async function resolveBackfill(db, opts = {}) {
+  return runBackfill(db, opts, resolveVerifyCompatibility, "backfill(resolve)");
+}
+async function drainCompatVerifyQueue(db, opts = {}) {
+  const limit = Math.max(1, opts.limit ?? 10);
+  const pending2 = await getPendingCompatVerify(db, limit);
+  let verified = 0;
+  let dropped = 0;
+  for (const req of pending2) {
+    const names = req.packages;
+    if (fullyCovered(names, await coveredPairs(db, names))) {
+      await deleteCompatVerify(db, req.id);
+      continue;
+    }
+    try {
+      const { edges } = await resolveVerifyCompatibility(db, names);
+      verified += edges.length;
+      await deleteCompatVerify(db, req.id);
+    } catch (err) {
+      logger.warn(`compat-verify drain failed for ${names.join(", ")}: ${String(err)}`);
+      const attempts = await bumpCompatVerifyAttempt(db, req.id);
+      if (attempts >= MAX_COMPAT_VERIFY_ATTEMPTS) {
+        await deleteCompatVerify(db, req.id);
+        dropped++;
+      }
+    }
+  }
+  logger.info(
+    `compat-verify: ${verified} edge(s) from ${pending2.length} queued set(s), ${dropped} dropped`
+  );
+  return { processed: pending2.length, verified, dropped };
+}
+var MAX_COMPAT_VERIFY_ATTEMPTS;
 var init_compat2 = __esm({
   "src/pipeline/compat.ts"() {
     "use strict";
     init_esm_shims();
+    init_logger();
     init_compat();
     init_packages();
     init_sandbox();
+    init_resolveCheck();
+    init_compat();
+    MAX_COMPAT_VERIFY_ATTEMPTS = 3;
   }
 });
 
@@ -5447,11 +5968,13 @@ var commands_exports = {};
 __export(commands_exports, {
   runCompare: () => runCompare,
   runCompat: () => runCompat,
+  runCompatBackfill: () => runCompatBackfill,
   runEditWeights: () => runEditWeights,
   runEvaluate: () => runEvaluate,
   runPlan: () => runPlan,
   runRecommend: () => runRecommend,
   runSandbox: () => runSandbox,
+  runUsage: () => runUsage,
   runVerify: () => runVerify,
   runVersions: () => runVersions,
   runWatch: () => runWatch,
@@ -5650,10 +6173,10 @@ async function openInBrowser(target) {
   spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
 }
 async function runPlan(file, opts) {
-  const { readFileSync: readFileSync4 } = await import("fs");
+  const { readFileSync: readFileSync3 } = await import("fs");
   let document;
   try {
-    document = readFileSync4(file, "utf8");
+    document = readFileSync3(file, "utf8");
   } catch {
     throw new Error(`Could not read "${file}".`);
   }
@@ -5673,10 +6196,10 @@ async function runPlan(file, opts) {
     }
     if (opts.html || opts.open) {
       const { writeFileSync: writeFileSync3 } = await import("fs");
-      const { tmpdir: tmpdir2 } = await import("os");
-      const { join: join5 } = await import("path");
+      const { tmpdir: tmpdir3 } = await import("os");
+      const { join: join6 } = await import("path");
       const { renderPlanHtml: renderPlanHtml2 } = await Promise.resolve().then(() => (init_planView(), planView_exports));
-      const out = opts.html ?? join5(tmpdir2(), `lurq-plan-${Date.now()}.html`);
+      const out = opts.html ?? join6(tmpdir3(), `lurq-plan-${Date.now()}.html`);
       writeFileSync3(out, renderPlanHtml2(res), "utf8");
       console.log(`Roadmap written to ${out}`);
       if (opts.open) await openInBrowser(out);
@@ -5799,6 +6322,57 @@ async function runSandbox(pkg, version, opts) {
     );
   });
 }
+async function runUsage(pkg, opts) {
+  await withDb(async (db) => {
+    const { handleUsage: handleUsage2 } = await Promise.resolve().then(() => (init_handlers(), handlers_exports));
+    const res = await handleUsage2(db, {
+      package: pkg,
+      version: opts.version,
+      knownVersion: opts.known
+    });
+    if (opts.json) return console.log(JSON.stringify(res, null, 2));
+    console.log(`${bold(res.package)}${res.version ? `@${res.version}` : ""}`);
+    if (!res.available) return console.log(dim(res.note ?? "no API surface available"));
+    console.log(
+      table(
+        ["Export", "Kind", "Signature"],
+        (res.surface ?? []).map((s) => [s.name, s.kind, s.signature ?? ""])
+      )
+    );
+    if (res.delta) {
+      const d = res.delta;
+      console.log(bold(`
+\u0394 from ${res.package}@${d.fromVersion}:`));
+      for (const s of d.removed) console.log(red(`  - ${s.name}`));
+      for (const s of d.added) console.log(green(`  + ${s.name}`));
+      for (const r of d.renamed) console.log(yellow(`  ~ ${r.from.name} \u2192 ${r.to.name}`));
+      for (const c of d.changed) console.log(yellow(`  ! ${c.name}: ${c.before ?? "?"} \u2192 ${c.after ?? "?"}`));
+      if (!d.removed.length && !d.added.length && !d.renamed.length && !d.changed.length) {
+        console.log(dim("  no API changes"));
+      }
+    }
+  });
+}
+async function runCompatBackfill(opts) {
+  await withDb(async (db) => {
+    const compat = await Promise.resolve().then(() => (init_compat2(), compat_exports));
+    if (opts.resolve) {
+      console.error(yellow("resolve-only backfill (npm resolution, no install/VM)"));
+      const res2 = await compat.resolveBackfill(db, opts);
+      console.log(
+        `${green("resolve backfill done")}: ${res2.verified} edges across ${res2.batches} runs, ${res2.skipped} batches skipped`
+      );
+      return;
+    }
+    console.error(
+      yellow("co-installing top packages in the sandbox (loads package code locally without isolation unless E2B_API_KEY is set)")
+    );
+    const res = await compat.backfillVerify(db, opts);
+    console.log(
+      `${green("backfill done")}: ${res.verified} edges across ${res.batches} runs, ${res.skipped} batches skipped`
+    );
+  });
+}
 async function runCompat(pkgs, opts) {
   await withDb(async (db) => {
     if (opts.run) {
@@ -5827,6 +6401,19 @@ async function runCompat(pkgs, opts) {
       console.log(dim(`
 unverified (no metadata): ${res.unverified.join(", ")}`));
     }
+    const compatEvidence = res.evidence.filter((e) => e.status === "compatible");
+    if (compatEvidence.length) {
+      console.log(
+        table(
+          ["Pair", "Evidence", "Witnesses"],
+          compatEvidence.map((e) => [
+            `${e.packages[0]} + ${e.packages[1]}`,
+            e.provenance,
+            e.provenance === "observed" ? String(e.witnessCount) : "\u2014"
+          ])
+        )
+      );
+    }
   });
 }
 var init_commands = __esm({
@@ -5862,9 +6449,9 @@ __export(installSkill_exports, {
 import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 import { copyFileSync } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname4, join as join4 } from "path";
+import { dirname as dirname4, join as join5 } from "path";
 function home(...p) {
-  return join4(homedir3(), ...p);
+  return join5(homedir3(), ...p);
 }
 function agentSpecs() {
   return [
@@ -5998,10 +6585,10 @@ function installAgent(spec, mode) {
   }
 }
 function installInstructionsFile() {
-  const src = join4(packageRoot(), "templates", "skill-instructions.md");
+  const src = join5(packageRoot(), "templates", "skill-instructions.md");
   if (!existsSync4(src)) return null;
   const destDir = home(".lurq");
-  const dest = join4(destDir, "skill-instructions.md");
+  const dest = join5(destDir, "skill-instructions.md");
   mkdirSync2(destDir, { recursive: true });
   copyFileSync(src, dest);
   return dest;
@@ -6212,245 +6799,6 @@ var init_install = __esm({
   }
 });
 
-// src/cli/keys.ts
-var keys_exports = {};
-__export(keys_exports, {
-  runKeysCreate: () => runKeysCreate,
-  runKeysList: () => runKeysList,
-  runKeysRevoke: () => runKeysRevoke,
-  runKeysRotate: () => runKeysRotate
-});
-function waitForEnter(prompt) {
-  return new Promise((resolve) => {
-    process.stdout.write(prompt);
-    process.stdin.resume();
-    process.stdin.once("data", () => {
-      process.stdin.pause();
-      resolve();
-    });
-  });
-}
-async function presentNewKey(key, row, opts) {
-  if (opts.json) {
-    console.log(
-      JSON.stringify({ key, prefix: row.prefix, tier: row.tier, label: row.label, ...opts.extraJson })
-    );
-    return;
-  }
-  const meta = `prefix=${row.prefix}  tier=${row.tier}${row.label ? `  label=${row.label}` : ""}`;
-  const block = [bold(opts.header ?? "API key created."), "", `  ${green(key)}`, "", dim(meta)];
-  console.log(block.join("\n"));
-  if (process.stdout.isTTY && process.stdin.isTTY) {
-    await waitForEnter(dim("Copy it now, then press Enter to erase it from the terminal\u2026 "));
-    process.stdout.write(`\x1B[${block.length + 1}F\x1B[0J\x1B[3J`);
-    console.log(
-      dim(`New key (prefix ${row.prefix}) erased from the terminal. It is stored only as a hash and cannot be recovered, so make sure you saved it.`)
-    );
-  } else {
-    console.log(dim("Store it now \u2014 shown only once, stored hashed, cannot be recovered."));
-  }
-}
-async function runKeysCreate(opts) {
-  requireConfig(["DATABASE_URL"]);
-  const { db, close } = createDb({ max: 1 });
-  try {
-    const { key, row } = await createKey(db, {
-      label: opts.label,
-      tier: opts.tier,
-      ownerId: opts.owner
-    });
-    await presentNewKey(key, row, opts);
-  } finally {
-    await close();
-  }
-}
-async function runKeysRotate(prefixOrId, opts) {
-  requireConfig(["DATABASE_URL"]);
-  const { db, close } = createDb({ max: 1 });
-  try {
-    const result = await rotateKey(db, prefixOrId);
-    if (!result) {
-      logger.warn(`No active key matched "${prefixOrId}".`);
-      process.exitCode = 1;
-      return;
-    }
-    await presentNewKey(result.key, result.row, {
-      json: opts.json,
-      header: `API key rotated \u2014 replaces ${result.previous.prefix} (now revoked).`,
-      extraJson: { replaced: result.previous.prefix }
-    });
-  } finally {
-    await close();
-  }
-}
-async function runKeysList(opts) {
-  requireConfig(["DATABASE_URL"]);
-  const { db, close } = createDb({ max: 1 });
-  try {
-    const rows = await listKeys(db);
-    if (opts.json) {
-      console.log(
-        JSON.stringify(
-          rows.map((r) => ({
-            id: r.id,
-            prefix: r.prefix,
-            label: r.label,
-            tier: r.tier,
-            ownerId: r.ownerId,
-            createdAt: r.createdAt,
-            lastUsedAt: r.lastUsedAt,
-            revokedAt: r.revokedAt
-          })),
-          null,
-          2
-        )
-      );
-      return;
-    }
-    if (rows.length === 0) {
-      console.log("No API keys yet. Create one with `lurq keys create --label <name>`.");
-      return;
-    }
-    console.log(
-      table(
-        ["prefix", "label", "tier", "created", "last used", "status"],
-        rows.map((r) => [
-          r.prefix,
-          r.label ?? "\u2014",
-          r.tier,
-          isoDay(r.createdAt),
-          isoDay(r.lastUsedAt),
-          r.revokedAt ? "revoked" : "active"
-        ])
-      )
-    );
-  } finally {
-    await close();
-  }
-}
-async function runKeysRevoke(prefixOrId) {
-  requireConfig(["DATABASE_URL"]);
-  const { db, close } = createDb({ max: 1 });
-  try {
-    const n = await revokeKey(db, prefixOrId);
-    if (n === 0) {
-      logger.warn(`No active key matched "${prefixOrId}".`);
-      process.exitCode = 1;
-      return;
-    }
-    console.log(`Revoked ${n} key(s) matching "${prefixOrId}".`);
-  } finally {
-    await close();
-  }
-}
-var isoDay;
-var init_keys = __esm({
-  "src/cli/keys.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_config();
-    init_logger();
-    init_apiKeys();
-    init_client();
-    init_format();
-    isoDay = (d) => d ? d.toISOString().slice(0, 10) : "\u2014";
-  }
-});
-
-// src/db/seed.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { sql as sql5 } from "drizzle-orm";
-import { z as z3 } from "zod";
-function loadSeedFile(path2 = seedJsonPath()) {
-  const raw = JSON.parse(readFileSync3(path2, "utf8"));
-  const parsed = SeedFileSchema.parse(raw);
-  const byName = /* @__PURE__ */ new Map();
-  for (const entry of parsed) {
-    if (!byName.has(entry.name)) byName.set(entry.name, entry);
-  }
-  return [...byName.values()];
-}
-async function loadSeedPackages(db, path2) {
-  const entries = loadSeedFile(path2);
-  if (entries.length === 0) return 0;
-  await db.insert(seedPackages).values(entries.map((e) => ({ name: e.name, category: e.category ?? null }))).onConflictDoUpdate({
-    target: seedPackages.name,
-    // Refresh category to the incoming value on conflict (EXCLUDED.category).
-    set: { category: sql5`excluded.category` }
-  });
-  logger.info(`Loaded ${entries.length} packages into seed_packages.`);
-  return entries.length;
-}
-var SeedEntrySchema, SeedFileSchema;
-var init_seed = __esm({
-  "src/db/seed.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_types();
-    init_logger();
-    init_paths();
-    init_schema();
-    SeedEntrySchema = z3.object({
-      name: z3.string().min(1),
-      category: z3.enum(CATEGORIES).optional()
-    });
-    SeedFileSchema = z3.array(SeedEntrySchema);
-  }
-});
-
-// src/db/migrate.ts
-var migrate_exports = {};
-__export(migrate_exports, {
-  runMigrate: () => runMigrate,
-  runReset: () => runReset
-});
-import { migrate } from "drizzle-orm/postgres-js/migrator";
-async function ensureVectorExtension(handle) {
-  try {
-    await handle.sql`CREATE EXTENSION IF NOT EXISTS vector`;
-  } catch (err) {
-    logger.warn(
-      `CREATE EXTENSION vector did not run cleanly (continuing to migrations): ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-}
-async function runMigrate() {
-  const handle = createDb({ max: 1 });
-  try {
-    logger.info("Ensuring pgvector extension\u2026");
-    await ensureVectorExtension(handle);
-    logger.info("Applying migrations\u2026");
-    await migrate(handle.db, { migrationsFolder: migrationsDir() });
-    logger.info("Loading seed list\u2026");
-    await loadSeedPackages(handle.db);
-    logger.info("Migration complete.");
-  } finally {
-    await handle.close();
-  }
-}
-async function runReset() {
-  const handle = createDb({ max: 1 });
-  try {
-    logger.warn("Dropping schema `public` (destructive)\u2026");
-    await handle.sql.unsafe("DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public;");
-    await handle.sql`DROP SCHEMA IF EXISTS drizzle CASCADE`;
-  } finally {
-    await handle.close();
-  }
-  await runMigrate();
-  logger.info("Reset complete.");
-}
-var init_migrate = __esm({
-  "src/db/migrate.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_logger();
-    init_paths();
-    init_client();
-    init_seed();
-  }
-});
-
 // src/index.ts
 init_esm_shims();
 init_types();
@@ -6475,12 +6823,6 @@ function buildProgram() {
     const { startHttpServer: startHttpServer2 } = await Promise.resolve().then(() => (init_http2(), http_exports));
     await startHttpServer2({ port: opts.port });
   });
-  program.command("sync").description("run ingestion: refresh scores for the seed list (or one package)").option("--full", "force a full re-sync, ignoring cache TTLs").option("--package <name>", "sync a single package by name").option("--json", "output the run summary as JSON").action(async (opts) => {
-    const { runSync: runSync2 } = await Promise.resolve().then(() => (init_pipeline(), pipeline_exports));
-    const summary = await runSync2({ full: opts.full, packageName: opts.package });
-    if (opts.json) console.log(JSON.stringify(summary, null, 2));
-    if (summary.status === "failed") process.exitCode = 1;
-  });
   program.command("recommend").argument("<need>", "natural-language description of what you need").description("recommend the best current packages for a described need").option("--category <category>", "restrict to a taxonomy category").option("--min-confidence <level>", "proven | emerging | promising | unproven").option("--json", "output JSON instead of a table").action(async (need, opts) => {
     const { runRecommend: runRecommend2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
     await runRecommend2(need, opts);
@@ -6497,6 +6839,10 @@ function buildProgram() {
     const { runVerify: runVerify2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
     await runVerify2(pkg, opts);
   });
+  program.command("usage").argument("<package>", "npm package name").description("version-exact API surface (exported symbols/signatures) + drift from a known version").option("--version <v>", "target version (defaults to latest)").option("--known <v>", "a version you know; shows the API delta to the target").option("--json", "output JSON").action(async (pkg, opts) => {
+    const { runUsage: runUsage2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+    await runUsage2(pkg, opts);
+  });
   program.command("versions").argument("<package>", "npm package name").description("show the stored version timeline for a package").option("--json", "output JSON instead of a table").option("-n, --limit <n>", "how many versions to show (default 30)").action(async (pkg, opts) => {
     const { runVersions: runVersions2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
     await runVersions2(pkg, opts);
@@ -6513,35 +6859,7 @@ function buildProgram() {
     const { runEditWeights: runEditWeights2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
     await runEditWeights2(opts);
   });
-  program.command("discover").description("operator-side: proactively crawl for new packages and queue/gate them (\xA72B)").option("--cap <n>", "max candidates to fully ingest this run", (v) => parseInt(v, 10)).option("--dry-run", "discover, queue, and gate, but do not ingest survivors").option("--json", "output the discovery summary as JSON").action(async (opts) => {
-    const { requireConfig: requireConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
-    requireConfig2(["DATABASE_URL"]);
-    const { runDiscovery: runDiscovery2 } = await Promise.resolve().then(() => (init_pipeline(), pipeline_exports));
-    const summary = await runDiscovery2({ perRunCap: opts.cap, dryRun: opts.dryRun });
-    if (opts.json) console.log(JSON.stringify(summary, null, 2));
-  });
-  program.command("rescore").description("re-derive health scores from cached breakdowns using current weights (no re-ingest)").option("--json", "output the rescore summary as JSON").action(async (opts) => {
-    const { requireConfig: requireConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
-    requireConfig2(["DATABASE_URL"]);
-    const { runRescore: runRescore2 } = await Promise.resolve().then(() => (init_pipeline(), pipeline_exports));
-    const summary = await runRescore2();
-    if (opts.json) console.log(JSON.stringify(summary, null, 2));
-  });
-  program.command("watch").description(
-    "operator-side: follow the npm changes feed, re-syncing tracked packages on new releases"
-  ).action(async () => {
-    const { runWatch: runWatch2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
-    await runWatch2();
-  });
-  program.command("sandbox").argument("<package>", "npm package name").argument("[version]", "specific version (default: latest)").description(
-    "operator-side: install + smoke-load a package in a sandbox to verify it actually works"
-  ).option("--esm", "load via ESM import instead of CJS require").option("--allow-scripts", "run install scripts (UNSAFE without VM isolation)").option("--json", "output JSON").action(
-    async (pkg, version, opts) => {
-      const { runSandbox: runSandbox2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
-      await runSandbox2(pkg, version, opts);
-    }
-  );
-  program.command("compat").argument("<packages...>", "npm package names to check together").description("check pairwise compatibility of packages from the sandbox matrix").option("--run", "operator-side: co-install them in the sandbox first (UNSAFE without VM isolation)").option("--json", "output JSON").action(async (pkgs, opts) => {
+  program.command("compat").argument("<packages...>", "npm package names to check together").description("check whether a set of packages forms a coherent stack (peer/engine + recorded evidence)").option("--json", "output JSON").action(async (pkgs, opts) => {
     const { runCompat: runCompat2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
     await runCompat2(pkgs, opts);
   });
@@ -6557,39 +6875,6 @@ function buildProgram() {
     const { runInstallSkill: runInstallSkill2 } = await Promise.resolve().then(() => (init_installSkill(), installSkill_exports));
     await runInstallSkill2(opts);
   });
-  const keys = program.command("keys").description("manage API keys for the hosted service (operator; needs DATABASE_URL)");
-  keys.command("create").description("create a new API key (shown once; erased from the terminal after you copy it)").option("--label <label>", "human label (owner / org / purpose)").option("--tier <tier>", "tier name", "free").option("--owner <id>", "org/owner id to attribute this key to (e.g. a Clerk org id)").option("--json", "print the key as JSON and skip the interactive erase (for scripts)").action(async (opts) => {
-    const { runKeysCreate: runKeysCreate2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
-    await runKeysCreate2(opts);
-  });
-  keys.command("list").description("list issued API keys (hashes are never shown)").option("--json", "output as JSON").action(async (opts) => {
-    const { runKeysList: runKeysList2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
-    await runKeysList2(opts);
-  });
-  keys.command("rotate").argument("<prefixOrId>", "key prefix (e.g. lurq_live_ab12cd) or numeric id to replace").description("issue a replacement key (same label/tier) and revoke the old one").option("--json", "print the new key as JSON and skip the interactive erase (for scripts)").action(async (prefixOrId, opts) => {
-    const { runKeysRotate: runKeysRotate2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
-    await runKeysRotate2(prefixOrId, opts);
-  });
-  keys.command("revoke").argument("<prefixOrId>", "key prefix (e.g. lurq_live_ab12cd) or numeric id").description("revoke an API key").action(async (prefixOrId) => {
-    const { runKeysRevoke: runKeysRevoke2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
-    await runKeysRevoke2(prefixOrId);
-  });
-  const db = program.command("db").description("database management");
-  db.command("migrate").description("apply database migrations and load the seed list").action(async () => {
-    const { runMigrate: runMigrate2 } = await Promise.resolve().then(() => (init_migrate(), migrate_exports));
-    await runMigrate2();
-  });
-  db.command("reset").description("drop and recreate the schema (destructive)").option("--yes", "skip the confirmation prompt").action(async (opts) => {
-    if (!opts.yes) {
-      console.error(
-        "Refusing to reset without confirmation. Re-run with `--yes` to drop and recreate the schema."
-      );
-      process.exitCode = 1;
-      return;
-    }
-    const { runReset: runReset2 } = await Promise.resolve().then(() => (init_migrate(), migrate_exports));
-    await runReset2();
-  });
   return program;
 }
 export {
@@ -6601,6 +6886,7 @@ export {
   EMBEDDING_DIM,
   FRONTEND_CATEGORIES,
   PACKAGE_NAME,
+  PROVENANCE_RANK,
   SERVER_NAME,
   STALENESS_DAYS,
   VERSION,