@blamejs/exceptd-skills 0.12.13 → 0.12.15

package/lib/source-osv.js

@@ -38,6 +38,7 @@
 
 const https = require("https");
 const fs = require("fs");
+const { withRetry } = require("../vendor/blamejs/retry.js");
 
 // OSV_HOST_OVERRIDE lets tests redirect the network call to a local HTTP
 // server bound on 127.0.0.1:<port>. The override accepts either a bare
@@ -77,6 +78,21 @@ const OSV_ID_PREFIXES = [
   "OPENSUSE-", // openSUSE
 ];
 
+/**
+ * Set of OSV draft fields the field-dropped detector watches. When a
+ * previously-populated value goes to null on a refresh, surface it as a
+ * `field_dropped` diff so curators can investigate the upstream regression
+ * rather than silently losing signal. Keep this set small + intentional —
+ * fields here MUST be ones the editorial review process can re-source.
+ */
+const FIELD_DROPPED_WATCH = Object.freeze([
+  "cvss_score",
+  "cisa_kev_pending",
+  "active_exploitation",
+  "ai_discovered",
+  "poc_available",
+]);
+
 /**
  * Return true when `id` looks like an OSV-native primary key (i.e. NOT a
  * CVE-* identifier and NOT a GHSA-* identifier). Both CVE-* and GHSA-*
@@ -84,98 +100,119 @@ const OSV_ID_PREFIXES = [
  */
 function isOsvId(id) {
   if (!id || typeof id !== "string") return false;
-  const up = id.toUpperCase();
+  // F8 (finding 8): trim trailing/leading whitespace so operators pasting
+  // ids from clipboards / multi-line files don't see a surprising routing
+  // miss. Empty after trim → not an OSV id.
+  const trimmed = id.trim();
+  if (!trimmed) return false;
+  const up = trimmed.toUpperCase();
   if (/^CVE-\d{4}-\d+$/.test(up)) return false;
   if (up.startsWith("GHSA-")) return false;
   return OSV_ID_PREFIXES.some((p) => up.startsWith(p));
 }
 
+/**
+ * Return true when the runtime context requests air-gap mode. Sources MUST
+ * refuse network calls when this is set — fall through to fixture or return
+ * a structured `air-gap: no fixture available` error so the operator sees
+ * an explicit refusal, not a silent network attempt.
+ */
+function isAirGap(opts) {
+  if (opts && opts.airGap) return true;
+  if (process.env.EXCEPTD_AIR_GAP === "1") return true;
+  return false;
+}
+
 /**
  * Resolve the OSV transport target. When OSV_HOST_OVERRIDE is set the
  * request switches to plain HTTP on the override host:port so test
  * harnesses can stand up a local server without TLS. Production omits the
  * override entirely and lands on api.osv.dev over HTTPS.
+ *
+ * Finding 13: validate the override aggressively. Garbage env values
+ * (random binary, embedded NUL, port > 65535) previously slipped through
+ * into the http.request options and produced opaque ENOTFOUND / EADDRINUSE
+ * errors far from the source. Reject with a structured error here instead.
  */
 function osvTransport() {
   const override = process.env.OSV_HOST_OVERRIDE;
   if (!override) return { mod: https, host: OSV_HOST, port: 443 };
-  // Accept either "host:port" or a full URL.
-  let raw = override.trim();
+  const raw = String(override).trim();
+  const HOST_RE = /^[a-z0-9.-]+$/i;
+  let host;
+  let port;
   if (/^https?:\/\//i.test(raw)) {
-    const u = new URL(raw);
-    return { mod: require("http"), host: u.hostname, port: parseInt(u.port, 10) || 80 };
+    let u;
+    try { u = new URL(raw); }
+    catch (e) {
+      return { error: `OSV_HOST_OVERRIDE: invalid URL: ${e.message}` };
+    }
+    host = u.hostname;
+    port = parseInt(u.port, 10);
+    if (!port) port = u.protocol === "https:" ? 443 : 80;
+  } else {
+    const [h, p] = raw.split(":");
+    host = h;
+    port = parseInt(p, 10) || 80;
   }
-  const [h, p] = raw.split(":");
-  return { mod: require("http"), host: h || "127.0.0.1", port: parseInt(p, 10) || 80 };
+  if (!host || !HOST_RE.test(host)) {
+    return { error: `OSV_HOST_OVERRIDE: invalid host '${host || ""}'; must match /^[a-z0-9.-]+$/i` };
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    return { error: `OSV_HOST_OVERRIDE: invalid port '${port}'; must be 1..65535` };
+  }
+  return { mod: require("http"), host, port };
 }
 
 /**
- * Low-level GET against OSV. Resolves to { ok, record|error, source }.
- * Honors OSV_HOST_OVERRIDE for offline tests.
+ * Make one OSV request (HEAD/GET/POST). Throws on retryable conditions
+ * (HTTP 429/503/5xx + ECONNRESET/ETIMEDOUT family) and resolves to a
+ * structured `{ok:false}` envelope on permanent conditions (4xx other than
+ * 408/425/429). The thrown errors carry `statusCode` so withRetry's default
+ * classifier recognizes them as retryable.
  */
-function osvGet(reqPath, timeoutMs = REQUEST_TIMEOUT_MS) {
-  return new Promise((resolve) => {
-    const { mod, host, port } = osvTransport();
-    const req = mod.get({
-      host,
-      port,
-      path: reqPath,
-      headers: {
-        "Accept": "application/json",
-        "User-Agent": USER_AGENT,
-      },
-      timeout: timeoutMs,
-    }, (res) => {
-      if (res.statusCode !== 200) {
+function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const t = osvTransport();
+    if (t.error) {
+      // F13: surface the validation error structurally; no retry.
+      return resolve({ ok: false, error: t.error, source: "offline" });
+    }
+    const { mod, host, port } = t;
+    const headers = {
+      "Accept": "application/json",
+      "User-Agent": USER_AGENT,
+    };
+    let payload = null;
+    if (method === "POST" && body) {
+      payload = Buffer.from(JSON.stringify(body), "utf8");
+      headers["Content-Type"] = "application/json";
+      headers["Content-Length"] = payload.length;
+    }
+    const opts = { host, port, path: reqPath, method, headers, timeout: timeoutMs };
+    const req = mod.request(opts, (res) => {
+      const status = res.statusCode;
+      // 401/404 (and other 4xx aside from 408/425/429) are permanent.
+      // 429/503 + 5xx are retryable. Honor Retry-After when present.
+      const retryAfterRaw = res.headers["retry-after"];
+      if (status === 429 || status === 503 || (status >= 500 && status <= 599) ||
+          status === 408 || status === 425) {
         res.resume();
-        const status = res.statusCode;
-        const error = status === 429
-          ? `OSV rate-limited (HTTP 429)`
-          : `OSV returned HTTP ${status}`;
-        return resolve({ ok: false, error, status, source: "offline" });
-      }
-      const chunks = [];
-      res.on("data", (c) => chunks.push(c));
-      res.on("end", () => {
-        try {
-          const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-          resolve({ ok: true, record: body, source: "osv-api" });
-        } catch (e) {
-          resolve({ ok: false, error: `parse: ${e.message}`, source: "offline" });
+        const err = new Error(`OSV returned HTTP ${status}`);
+        err.statusCode = status;
+        // Surface Retry-After (seconds or HTTP-date). The retry caller
+        // doesn't currently consume this directly — withRetry's backoff is
+        // its own schedule — but exposing it lets future schedulers honor
+        // server-advertised delay.
+        if (retryAfterRaw) {
+          const secs = parseInt(retryAfterRaw, 10);
+          if (Number.isFinite(secs)) err.retryAfterMs = secs * 1000;
         }
-      });
-    });
-    req.on("timeout", () => req.destroy(new Error("OSV request timed out")));
-    req.on("error", (e) => resolve({ ok: false, error: e.message, source: "offline" }));
-  });
-}
-
-/**
- * Low-level POST against OSV. Body is JSON-stringified.
- */
-function osvPost(reqPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
-  return new Promise((resolve) => {
-    const payload = Buffer.from(JSON.stringify(body), "utf8");
-    const { mod, host, port } = osvTransport();
-    const req = mod.request({
-      host,
-      port,
-      path: reqPath,
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Content-Length": payload.length,
-        "Accept": "application/json",
-        "User-Agent": USER_AGENT,
-      },
-      timeout: timeoutMs,
-    }, (res) => {
-      if (res.statusCode !== 200) {
+        return reject(err);
+      }
+      if (status !== 200) {
         res.resume();
-        const status = res.statusCode;
-        const error = status === 429
-          ? `OSV rate-limited (HTTP 429)`
-          : `OSV returned HTTP ${status}`;
+        const error = `OSV returned HTTP ${status}`;
         return resolve({ ok: false, error, status, source: "offline" });
       }
       const chunks = [];
@@ -189,13 +226,73 @@ function osvPost(reqPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
         }
       });
     });
-    req.on("timeout", () => req.destroy(new Error("OSV request timed out")));
-    req.on("error", (e) => resolve({ ok: false, error: e.message, source: "offline" }));
-    req.write(payload);
+    req.on("timeout", () => {
+      const err = new Error("OSV request timed out");
+      err.code = "ETIMEDOUT";
+      req.destroy(err);
+    });
+    req.on("error", (e) => {
+      // Retryable network errors propagate up to withRetry; non-retryable
+      // resolve as structured offline.
+      if (e && e.code && /^(ECONNRESET|ECONNREFUSED|ECONNABORTED|ETIMEDOUT|EPIPE|EAGAIN|ENOTFOUND|ENETUNREACH)$/.test(e.code)) {
+        return reject(e);
+      }
+      resolve({ ok: false, error: e.message, source: "offline" });
+    });
+    if (payload) req.write(payload);
     req.end();
   });
 }
 
+/**
+ * Low-level GET against OSV. Resolves to { ok, record|error, source }.
+ * Honors OSV_HOST_OVERRIDE for offline tests. Wraps the request in
+ * withRetry so 429/503/5xx + transient net errors back off automatically.
+ */
+async function osvGet(reqPath, timeoutMs = REQUEST_TIMEOUT_MS) {
+  try {
+    return await withRetry(() => osvRequestOnce({ method: "GET", reqPath, timeoutMs }), {
+      maxAttempts: 3,
+      baseDelayMs: 100,
+      maxDelayMs: 2000,
+      jitterFactor: 0.5,
+    });
+  } catch (e) {
+    // After exhaustion of retries, return a structured envelope rather
+    // than letting the throw escape into the caller's promise chain.
+    const status = typeof e?.statusCode === "number" ? e.statusCode : null;
+    const error = status === 429
+      ? `OSV rate-limited (HTTP 429)`
+      : status
+        ? `OSV returned HTTP ${status}`
+        : `OSV request failed: ${e.message || e}`;
+    return { ok: false, error, status, source: "offline" };
+  }
+}
+
+/**
+ * Low-level POST against OSV. Body is JSON-stringified. Same retry policy
+ * as osvGet — 429/503/5xx + transient net errors back off automatically.
+ */
+async function osvPost(reqPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
+  try {
+    return await withRetry(() => osvRequestOnce({ method: "POST", reqPath, body, timeoutMs }), {
+      maxAttempts: 3,
+      baseDelayMs: 100,
+      maxDelayMs: 2000,
+      jitterFactor: 0.5,
+    });
+  } catch (e) {
+    const status = typeof e?.statusCode === "number" ? e.statusCode : null;
+    const error = status === 429
+      ? `OSV rate-limited (HTTP 429)`
+      : status
+        ? `OSV returned HTTP ${status}`
+        : `OSV request failed: ${e.message || e}`;
+    return { ok: false, error, status, source: "offline" };
+  }
+}
+
 /**
  * Read EXCEPTD_OSV_FIXTURE and return a structured envelope. Matches the
  * GHSA-source convention: on any failure (missing file, malformed JSON,
@@ -241,11 +338,14 @@ async function fetchAdvisoryById(id, opts = {}) {
     return { ok: false, error: "id is required (MAL-*, SNYK-*, RUSTSEC-*, etc.)", source: "offline" };
   }
   // OSV.dev's /v1/vulns/{id} is case-sensitive — `mal-2026-3083` 404s while
-  // `MAL-2026-3083` resolves. Uppercase at entry so operators piping
+  // `MAL-2026-3083` resolves. Uppercase + trim at entry so operators piping
   // lowercase ids from grep/jq don't get a surprising 404 from the network
   // path. Fixture lookup already case-folds, so this normalization is a
   // no-op there but harmless.
-  id = id.toUpperCase();
+  id = id.trim().toUpperCase();
+  if (!id) {
+    return { ok: false, error: "id is required (MAL-*, SNYK-*, RUSTSEC-*, etc.)", source: "offline" };
+  }
   const fixture = readFixture();
   if (fixture) {
     if (!fixture.ok) return fixture; // F1: structured error envelope
@@ -259,6 +359,12 @@ async function fetchAdvisoryById(id, opts = {}) {
     if (!match) return { ok: false, error: `${id} not in fixture`, source: "fixture" };
     return { ok: true, advisories: [match], source: "fixture" };
   }
+  // Finding 7: air-gap mode hard-refuses network calls. Operators running
+  // `exceptd refresh --air-gap` without a fixture get a structured refusal,
+  // not an outbound DNS query.
+  if (isAirGap(opts)) {
+    return { ok: false, error: "air-gap: no fixture available (set EXCEPTD_OSV_FIXTURE)", source: "offline" };
+  }
   const result = await osvGet(`/v1/vulns/${encodeURIComponent(id)}`, opts.timeoutMs);
   if (!result.ok) return result;
   return { ok: true, advisories: [result.record], source: "osv-api" };
@@ -290,6 +396,10 @@ async function fetchAdvisoriesForPackage(name, ecosystem, version, opts = {}) {
     });
     return { ok: true, advisories: matches, source: "fixture" };
   }
+  // Finding 7: air-gap refusal applies to the package query path too.
+  if (isAirGap(opts)) {
+    return { ok: false, error: "air-gap: no fixture available (set EXCEPTD_OSV_FIXTURE)", source: "offline" };
+  }
   const body = { package: { name, ecosystem } };
   if (version) body.version = version;
   const r = await osvPost("/v1/query", body, opts.timeoutMs);
@@ -302,12 +412,19 @@ async function fetchAdvisoriesForPackage(name, ecosystem, version, opts = {}) {
  * Pick the catalog key for an OSV record. If `aliases` contains a CVE-*
  * value, prefer that (preserving the existing CVE-keyed convention).
  * Otherwise return the OSV id verbatim — MAL-*, SNYK-*, RUSTSEC-*, etc.
+ *
+ * Finding 14: the non-CVE branch must String-coerce + uppercase so a
+ * record with `id: 12345` (numeric) or `id: "mal-2026-3083"` (lowercase)
+ * doesn't produce a catalog key that diverges from the canonical
+ * uppercase-prefix convention. The CVE branch already upper-cases via
+ * `String(cve).toUpperCase()`.
  */
 function pickCatalogKey(rec) {
-  if (!rec || !rec.id) return null;
+  if (!rec || rec.id == null) return null;
   const aliases = Array.isArray(rec.aliases) ? rec.aliases : [];
   const cve = aliases.find((a) => /^CVE-\d{4}-\d+$/i.test(String(a)));
-  return cve ? String(cve).toUpperCase() : String(rec.id);
+  if (cve) return String(cve).toUpperCase();
+  return String(rec.id).toUpperCase();
 }
 
 /**
@@ -365,57 +482,101 @@ function cvss3BaseScore(vector) {
   } else {
     base = Math.min(1.08 * (impact + exploitability), 10);
   }
-  // roundUp1: round up to one decimal (CVSS 3.1 §7.1).
-  const rounded = Math.ceil(base * 10) / 10;
-  if (!Number.isFinite(rounded) || rounded < 0 || rounded > 10) return null;
-  return rounded;
+  // roundUp1 per CVSS 3.1 §7.1: round up to one decimal place. The spec
+  // uses an integer-arithmetic formulation (Math.ceil(input * 100000) /
+  // 10000 / 10) to avoid floating-point off-by-ones (e.g. 5.55 -> 5.6,
+  // not 5.5 if naive `Math.ceil(base * 10) / 10` is applied to a value
+  // that lands at 5.5499999... after IEEE 754 rounding). Finding 11.
+  const rounded = Math.ceil(base * 100000) / 1000000 < 0
+    ? null
+    : (Math.ceil(base * 100000) / 100000); // intermediate at 5 decimals
+  if (rounded == null) return null;
+  // Now round-up to 1 decimal from the high-precision intermediate.
+  const out = Math.ceil(rounded * 10 - 1e-9) / 10;
+  if (!Number.isFinite(out) || out < 0 || out > 10) return null;
+  return Math.round(out * 10) / 10; // strip trailing fp noise
 }
 
 /**
  * Pull a numeric CVSS score + vector out of an OSV severity[] entry. CVSS
  * vectors start with "CVSS:3.x/" or "CVSS:4.0/". When multiple vectors are
- * present (e.g. both V3 and V4), the highest version wins regardless of
- * array order. When the OSV record has no embedded numeric tail, the score
- * is computed from the vector itself via cvss3BaseScore(). Returns null
- * components when nothing parseable is present.
+ * present (e.g. both V3 and V4), the highest version wins — UNLESS the v4
+ * vector cannot be scored (this module does not implement CVSS 4.0
+ * derivation yet), in which case fall back to the highest computable
+ * version below v4 so we don't silently lose a v3 9.8 (Finding 10).
+ * Returns null components when nothing parseable is present.
+ *
+ * Finding 19: when `s.score` is an object (some Snyk records embed
+ * `{ value: "CVSS:3.1/..." }`), accept `s.score.value` as the string
+ * source rather than silently producing null.
  */
 function extractCvss(rec) {
   const sev = Array.isArray(rec?.severity) ? rec.severity : [];
   let score = null;
-  let bestVector = null;
-  let bestVersion = 0;
+  // Collect all parseable vectors keyed by major version so we can fall
+  // back from v4 -> v3 if v4 fails to compute.
+  const vectorsByVersion = new Map(); // version (number) -> vector string
+  let bareScore = null;
   for (const s of sev) {
-    if (typeof s?.score !== "string") continue;
-    const v = s.score.trim();
+    if (s == null) continue;
+    let raw = null;
+    if (typeof s.score === "string") raw = s.score;
+    else if (typeof s.score === "object" && s.score && typeof s.score.value === "string") {
+      raw = s.score.value; // Finding 19
+    }
+    if (raw == null) continue;
+    const v = raw.trim();
     // Bare numeric score (no vector prefix).
     const num = parseFloat(v);
     if (!Number.isNaN(num) && num >= 0 && num <= 10 && !v.includes("/")) {
-      if (score == null) score = num;
+      if (bareScore == null) bareScore = num;
       continue;
     }
     const m = v.match(/^CVSS:(\d+\.\d+)/);
     if (!m) continue;
     const ver = parseFloat(m[1]);
-    if (ver > bestVersion) {
-      bestVersion = ver;
-      bestVector = v;
-    }
+    // Keep the highest score within each major version.
+    const prev = vectorsByVersion.get(ver);
+    if (!prev) vectorsByVersion.set(ver, v);
   }
-  // If we picked a vector, try to read an embedded score from the trailing
-  // fragment (some Snyk records carry it as ".../9.3"). Otherwise compute
-  // it from the vector for CVSS 3.x. CVSS 4.0 base-score derivation is
-  // intentionally not implemented here — that's a v0.13 follow-up.
-  if (bestVector && score == null) {
-    const tail = bestVector.match(/\/(\d+(?:\.\d+)?)$/);
+  // F10: try versions in descending order. CVSS 4.0 derivation is not yet
+  // implemented here — if v4 was the highest but can't be computed, walk
+  // down to v3.x. Only return null when ALL versions fail.
+  const versions = Array.from(vectorsByVersion.keys()).sort((a, b) => b - a);
+  let bestVector = null;
+  for (const ver of versions) {
+    const candidate = vectorsByVersion.get(ver);
+    if (!candidate) continue;
+    bestVector = candidate;
+    const tail = candidate.match(/\/(\d+(?:\.\d+)?)$/);
     if (tail) {
-      const candidate = parseFloat(tail[1]);
-      if (candidate >= 0 && candidate <= 10) score = candidate;
+      const t = parseFloat(tail[1]);
+      if (t >= 0 && t <= 10) { score = t; break; }
+    }
+    if (/^CVSS:3\./.test(candidate)) {
+      const computed = cvss3BaseScore(candidate);
+      if (computed != null) { score = computed; break; }
     }
-    if (score == null && /^CVSS:3\./.test(bestVector)) {
-      const computed = cvss3BaseScore(bestVector);
-      if (computed != null) score = computed;
+    // v4 has no in-module computer — keep walking down to the next
+    // version. The bestVector tracker holds whatever was tried last;
+    // overwrite it with the next computable on the loop iteration.
+  }
+  // If we landed on an uncomputable v4 vector but a lower-version vector
+  // was usable, prefer the lower-version one's vector string so callers
+  // don't get a v4 vector + null score combo when v3 was available.
+  if (score == null && versions.length > 0) {
+    for (const ver of versions) {
+      if (ver >= 4) continue;
+      const candidate = vectorsByVersion.get(ver);
+      if (candidate) { bestVector = candidate; break; }
     }
   }
+  // F10 fix: if score is still null but we have a v4 vector + a bare
+  // score that came from a v3-only severity entry, prefer the v3 vector
+  // string when one exists. (Handles the case described in the audit:
+  // v4 is the highest version but uncomputable; a v3 vector with 9.8
+  // sits alongside. Without this fallback we lose the 9.8.)
+  if (score == null && bareScore != null) score = bareScore;
   return { score, vector: bestVector };
 }
 
@@ -425,7 +586,8 @@ function extractCvss(rec) {
  */
 function inferType(rec) {
   const ecos = new Set();
-  for (const a of (rec?.affected || [])) {
+  const affected = Array.isArray(rec?.affected) ? rec.affected : [];
+  for (const a of affected) {
     if (a?.package?.ecosystem) ecos.add(String(a.package.ecosystem).toLowerCase());
   }
   if (ecos.has("pypi") || ecos.has("pip")) return "supply-chain-pypi";
@@ -439,6 +601,23 @@ function inferType(rec) {
   return "supply-chain-other";
 }
 
+/**
+ * Validate + slice a published/modified timestamp string. Findings 2 + 17:
+ *  - typeof guard so non-string inputs (number, object, undefined) become
+ *    null instead of throwing on .slice().
+ *  - ISO-prefix regex + year sanity bound so garbage like "yesterday" or
+ *    "0001-01-01" doesn't pollute downstream surfaces.
+ */
+function safeDateSlice(value) {
+  if (typeof value !== "string") return null;
+  const head = value.slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(head)) return null;
+  const year = parseInt(head.slice(0, 4), 10);
+  const now = new Date().getUTCFullYear();
+  if (!Number.isFinite(year) || year < 1990 || year > now + 1) return null;
+  return head;
+}
+
 /**
  * Normalize an OSV record into the exceptd catalog draft shape. Returns
  * `{ [catalogKey]: <draft-entry> }` so callers can spread it into the
@@ -450,7 +629,10 @@ function inferType(rec) {
  * mark the entry for the strict catalog validator (warn, not error).
  */
 function normalizeAdvisory(rec) {
-  if (!rec || !rec.id) return null;
+  if (!rec || rec.id == null) return null;
+  // Trim id so trailing whitespace doesn't bleed into pickCatalogKey + key.
+  if (typeof rec.id === "string") rec = { ...rec, id: rec.id.trim() };
+  if (!rec.id) return null;
   const catalogKey = pickCatalogKey(rec);
   if (!catalogKey) return null;
 
@@ -463,7 +645,9 @@ function normalizeAdvisory(rec) {
 
   const affectedPackages = [];
   const affectedVersions = [];
-  for (const a of (rec.affected || [])) {
+  // Finding 3: rec.affected might not be an array — guard before iterating.
+  const affectedList = Array.isArray(rec.affected) ? rec.affected : [];
+  for (const a of affectedList) {
     const pkg = a?.package || {};
     if (pkg.name && pkg.ecosystem) {
       affectedPackages.push(`${pkg.ecosystem}:${pkg.name}`);
@@ -472,14 +656,46 @@ function normalizeAdvisory(rec) {
     for (const v of versions) {
       affectedVersions.push(`${pkg.name || "?"} == ${v}`);
     }
-    // Range bounds: surface "introduced/fixed" pairs as a textual range.
+    // Finding 16: walk events sequentially. OSV emits a stream of
+    // introduced/fixed/last_affected events; the historical implementation
+    // collected the FIRST `introduced` + FIRST `fixed` per range and
+    // emitted one range, losing re-introduction cycles (an introduced ->
+    // fixed -> introduced -> fixed sequence collapsed to one range).
+    // Sequential pairing produces ONE entry per (introduced, fixed |
+    // last-known-vulnerable) pair instead.
     const ranges = Array.isArray(a.ranges) ? a.ranges : [];
     for (const r of ranges) {
       const events = Array.isArray(r.events) ? r.events : [];
-      const intro = events.find((e) => e.introduced)?.introduced;
-      const fixed = events.find((e) => e.fixed)?.fixed;
-      if (intro || fixed) {
-        affectedVersions.push(`${pkg.name || "?"} >= ${intro || "0"}` + (fixed ? `, < ${fixed}` : ""));
+      let openIntro = null;
+      let lastKnownVulnerable = null;
+      for (const e of events) {
+        if (!e || typeof e !== "object") continue;
+        if (typeof e.introduced === "string") {
+          // Flush any prior open pair with whatever upper bound we have.
+          if (openIntro != null) {
+            const upper = lastKnownVulnerable ? `, <= ${lastKnownVulnerable}` : "";
+            affectedVersions.push(`${pkg.name || "?"} >= ${openIntro}${upper}`);
+            lastKnownVulnerable = null;
+          }
+          openIntro = e.introduced;
+        } else if (typeof e.fixed === "string") {
+          if (openIntro != null) {
+            affectedVersions.push(`${pkg.name || "?"} >= ${openIntro}, < ${e.fixed}`);
+            openIntro = null;
+            lastKnownVulnerable = null;
+          } else {
+            // Defensive: fixed-without-introduced — emit a fixed-only marker.
+            affectedVersions.push(`${pkg.name || "?"} < ${e.fixed}`);
+          }
+        } else if (typeof e.last_affected === "string") {
+          lastKnownVulnerable = e.last_affected;
+        }
+      }
+      // Trailing open range — no `fixed` ever observed. Emit as
+      // `>= introduced` (optionally with last_known_vulnerable upper).
+      if (openIntro != null) {
+        const upper = lastKnownVulnerable ? `, <= ${lastKnownVulnerable}` : "";
+        affectedVersions.push(`${pkg.name || "?"} >= ${openIntro}${upper}`);
       }
     }
   }
@@ -497,8 +713,10 @@ function normalizeAdvisory(rec) {
   }
 
   // Reference URLs — OSV `references` is `[{ type, url }, ...]`.
+  // Finding 20: guard non-array references silently truncating to [].
   const refUrls = [];
-  for (const r of (rec.references || [])) {
+  const refList = Array.isArray(rec.references) ? rec.references : [];
+  for (const r of refList) {
     if (r && typeof r.url === "string") refUrls.push(r.url);
   }
 
@@ -512,8 +730,9 @@ function normalizeAdvisory(rec) {
   const pending = severityWord === "critical" || (score != null && score >= 9.0);
 
   const today = new Date().toISOString().slice(0, 10);
-  const published = (rec.published || "").slice(0, 10) || null;
-  const modified = (rec.modified || "").slice(0, 10) || null;
+  // Finding 2 + 17: type-safe + format-validated date slicing.
+  const published = safeDateSlice(rec.published);
+  const modified = safeDateSlice(rec.modified);
 
   // OSV.dev canonical advisory URL — used as the primary vendor advisory.
   const osvUrl = `https://osv.dev/vulnerability/${encodeURIComponent(rec.id)}`;
@@ -600,11 +819,14 @@ function normalizeAdvisory(rec) {
  * Build a refresh diff for the refresh-external orchestrator. v0.12.10
  * supports targeted seeding: when `ctx.osv_ids` is populated, fetch each
  * id and emit one `_new_entry` diff per record that isn't already in the
- * local catalog. The broader package-watchlist path (bulk import from
- * a watched-packages list) is deferred to v0.13.
+ * local catalog. Finding 9: when the record already exists and a watched
+ * field has dropped from populated -> null, emit a `field_dropped` diff
+ * so curators see the upstream regression instead of silently absorbing it.
  */
 async function buildDiff(ctx) {
-  const ids = Array.isArray(ctx?.osv_ids) ? ctx.osv_ids : [];
+  // Finding 8: trim ids defensively at the entry seam.
+  const rawIds = Array.isArray(ctx?.osv_ids) ? ctx.osv_ids : [];
+  const ids = rawIds.map((x) => (typeof x === "string" ? x.trim() : "")).filter(Boolean);
   if (ids.length === 0) {
     return {
       status: "ok",
@@ -615,7 +837,8 @@ async function buildDiff(ctx) {
       summary: "OSV: no ids requested (set ctx.osv_ids to seed a draft, or pass --advisory <MAL-...> for one-shot import).",
     };
   }
-  const existingKeys = new Set(Object.keys(ctx.cveCatalog || {}));
+  const cveCatalog = ctx.cveCatalog || {};
+  const existingKeys = new Set(Object.keys(cveCatalog));
   const diffs = [];
   // F7: distinguish unreachable (fetch failed, network or 5xx) from
   // normalize-rejected (record fetched but normalization produced null).
@@ -623,15 +846,47 @@ async function buildDiff(ctx) {
   // network outage or a malformed upstream record.
   let unreachable = 0;
   let normalizeErrors = 0;
+  // Finding 18: ids that ARE in the catalog but skipped because of overlap
+  // are not "errors"; surface them so the summary doesn't read as silently
+  // dropping work. Particularly useful when a curator dispatches the same
+  // batch twice and wonders why nothing happened.
+  let ghsaOnlySkipped = 0;
   for (const id of ids) {
-    const r = await fetchAdvisoryById(id);
+    const r = await fetchAdvisoryById(id, { airGap: ctx.airGap });
     if (!r.ok) { unreachable++; continue; }
     const rec = r.advisories[0];
     if (!rec) { unreachable++; continue; }
     const normalized = normalizeAdvisory(rec);
     if (!normalized) { normalizeErrors++; continue; }
     const key = Object.keys(normalized)[0];
-    if (existingKeys.has(key)) continue;
+    if (existingKeys.has(key)) {
+      // Finding 9: field-dropped detection. Compare watched fields between
+      // the existing local entry and the freshly-normalized one. Emit a
+      // `field_dropped` diff per regression rather than a `_new_entry`.
+      const before = cveCatalog[key] || {};
+      const after = normalized[key];
+      let dropped = false;
+      for (const field of FIELD_DROPPED_WATCH) {
+        const had = before[field];
+        const has = after[field];
+        const wasPopulated = had !== null && had !== undefined && had !== "" && had !== false;
+        const isNowEmpty = has === null || has === undefined;
+        if (wasPopulated && isNowEmpty) {
+          diffs.push({
+            id: key,
+            field,
+            before: had,
+            after: null,
+            severity: null,
+            source: "osv",
+            variant: "field_dropped",
+          });
+          dropped = true;
+        }
+      }
+      if (!dropped) ghsaOnlySkipped++;
+      continue;
+    }
     diffs.push({
       id: key,
       field: "_new_entry",
@@ -642,13 +897,15 @@ async function buildDiff(ctx) {
     });
   }
   const errors = unreachable + normalizeErrors;
+  const summary = `OSV fetched ${ids.length} id(s); ${diffs.length} new entry diff(s), ${unreachable} unreachable, ${normalizeErrors} normalize-rejected, ${ghsaOnlySkipped} ghsa_only_skipped.`;
   return {
     status: errors === 0 ? "ok" : errors === ids.length ? "unreachable" : "partial",
     diffs,
     errors,
     unreachable_count: unreachable,
     normalize_error_count: normalizeErrors,
-    summary: `OSV fetched ${ids.length} id(s); ${diffs.length} new entry diff(s), ${unreachable} unreachable, ${normalizeErrors} normalize-rejected.`,
+    ghsa_only_skipped: ghsaOnlySkipped,
+    summary,
   };
 }
 
@@ -661,4 +918,6 @@ module.exports = {
   extractCvss,
   cvss3BaseScore,
   OSV_ID_PREFIXES,
+  FIELD_DROPPED_WATCH,
+  safeDateSlice,
 };