@bedolla/enriweb 0.1.6 → 0.1.8

package/dist/tools/WebSearchRegistryVerifier.js

@@ -1,19 +1,34 @@
+import { WebSearchRegistryHttpReader } from "./WebSearchRegistryHttpReader.js";
+import { sliceUtf8Safe } from "../shared/Utf8SafeTextSlicer.js";
 /**
  * Enriches web search results with registry version verification.
  */
 export class WebSearchRegistryVerifier {
+    /**
+     * Capped JSON HTTP reader owning the registry transport concerns.
+     */
+    httpReader;
     /**
      * NuGet V3 service index endpoint.
      */
     static NUGET_SERVICE_INDEX_URL = "https://api.nuget.org/v3/index.json";
+    /**
+     * Maximum bytes read from one npm packument (full-version manifest).
+     *
+     * @remarks
+     * Popular packages legitimately exceed the shared 5 MB registry cap
+     * (thousands of versions with full metadata); parity with the EnriCode
+     * client plane's 16 MiB download budget for the same endpoint.
+     */
+    static NPM_PACKUMENT_MAX_BYTES = 16_777_216;
     /**
      * Default concurrency for registry verification.
      */
     static DEFAULT_CONCURRENCY = 3;
     /**
-     * Maximum JSON payload accepted from a registry endpoint.
+     * Time one cached error entity stays fresh before a retry.
      */
-    static MAX_JSON_BYTES = 5_000_000;
+    static ERROR_CACHE_TTL_MS = 60 * 1000;
     /**
      * Maximum cached verification entries (LRU eviction beyond this count).
      */
@@ -26,6 +41,16 @@ export class WebSearchRegistryVerifier {
      * In-memory TTL cache.
      */
     cache;
+    /**
+     * In-flight verification promises keyed by cache key.
+     *
+     * @remarks
+     * Single-flight coalescing: concurrent MCP requests verifying the same
+     * entity join one registry fetch instead of racing duplicates. Entries
+     * are removed when the verification settles (success, error or caller
+     * abort), so the map never outlives its requests.
+     */
+    inFlight = new Map();
     /**
      * Cached NuGet service index resolution.
      */
@@ -36,6 +61,10 @@ export class WebSearchRegistryVerifier {
      * @param deps - Dependencies
      */
     constructor(deps) {
+        this.httpReader = new WebSearchRegistryHttpReader({
+            fetchImpl: deps.fetchImpl,
+            timeoutMs: deps.timeoutMs
+        });
         this.deps = deps;
         this.cache = new Map();
         this.nugetServiceIndexCache = null;
@@ -51,7 +80,11 @@ export class WebSearchRegistryVerifier {
         if (signal?.aborted) {
             return [];
         }
-        const candidates = this.collectCandidates(results);
+        // A non-array `results` payload (proxy shape drift) carries no
+        // candidates; it must degrade to unverified instead of throwing
+        // "results is not iterable" into the tool result.
+        const entries = Array.isArray(results) ? results : [];
+        const candidates = this.collectCandidates(entries);
         if (candidates.length === 0) {
             return [];
         }
@@ -59,9 +92,19 @@ export class WebSearchRegistryVerifier {
             if (signal?.aborted) {
                 throw new Error("Verificación cancelada por el cliente.");
             }
-            return await this.verifyCandidate(candidate.kind, candidate.name);
+            return await this.verifyCandidate(candidate.kind, candidate.name, signal);
         });
-        return await this.runWithConcurrencyLimit(tasks, WebSearchRegistryVerifier.DEFAULT_CONCURRENCY);
+        try {
+            return await this.runWithConcurrencyLimit(tasks, WebSearchRegistryVerifier.DEFAULT_CONCURRENCY);
+        }
+        catch (error) {
+            // Cancellation must degrade to unverified results, never fail the search
+            // whose results already succeeded.
+            if (signal?.aborted) {
+                return [];
+            }
+            throw error;
+        }
     }
     /**
      * Collects registry candidates from search result URLs.
@@ -134,51 +177,146 @@ export class WebSearchRegistryVerifier {
         }
         return candidates;
     }
+    /**
+     * Maximum `releases` pages followed per GitHub verification.
+     */
+    static GITHUB_RELEASES_MAX_PAGES = 3;
     /**
      * Verifies a single candidate, using cache when available.
      *
      * @param kind - Registry kind
      * @param name - Candidate name
+     * @param signal - Optional caller abort signal forwarded to registry fetches
      * @returns Verification result
      */
-    async verifyCandidate(kind, name) {
+    async verifyCandidate(kind, name, signal) {
         const cacheKey = `${kind}:${name.toLowerCase()}`;
         const nowMs = Date.now();
         const cached = this.cache.get(cacheKey);
         if (cached && cached.expiresAtMs > nowMs) {
+            // LRU semantics: `Map.set` on an existing key updates the value
+            // WITHOUT moving the insertion-order record (ECMAScript spec), so a
+            // true recency refresh requires delete-then-set; otherwise eviction
+            // below stays FIFO and evicts hot entries inserted early.
+            this.cache.delete(cacheKey);
+            this.cache.set(cacheKey, cached);
             return cached.value;
         }
-        let value;
-        try {
-            if (kind === "npm") {
-                value = await this.verifyNpm(name);
+        // Single-flight: concurrent MCP requests verifying the same entity
+        // join the in-flight promise instead of racing duplicate registry
+        // fetches (GitHub unauthenticated quota is 60 req/h per IP).
+        const inFlight = this.inFlight.get(cacheKey);
+        if (inFlight !== undefined) {
+            return await inFlight;
+        }
+        const verification = (async () => {
+            let value;
+            try {
+                if (kind === "npm") {
+                    value = await this.verifyNpm(name, signal);
+                }
+                else if (kind === "pypi") {
+                    value = await this.verifyPyPi(name, signal);
+                }
+                else if (kind === "crates") {
+                    value = await this.verifyCrates(name, signal);
+                }
+                else if (kind === "nuget") {
+                    value = await this.verifyNuGet(name, signal);
+                }
+                else {
+                    value = await this.verifyGitHub(name, signal);
+                }
             }
-            else if (kind === "pypi") {
-                value = await this.verifyPyPi(name);
+            catch (error) {
+                // Map transport noise to stable Spanish before caching so error
+                // entities never carry raw undici English strings downstream.
+                value = {
+                    kind,
+                    name,
+                    status: "error",
+                    error: WebSearchRegistryVerifier.describeFetchError(error)
+                };
+                // Caller cancellations are not transient registry failures: caching
+                // them would poison the next search with "Operación cancelada…" rows,
+                // so the entity is returned uncached and re-verified on the next call.
+                if (WebSearchRegistryVerifier.isCallerCancellation(error, signal)) {
+                    return value;
+                }
             }
-            else if (kind === "crates") {
-                value = await this.verifyCrates(name);
+            const ttlMs = value.status === "error" ? WebSearchRegistryVerifier.ERROR_CACHE_TTL_MS : this.deps.cacheTtlMs;
+            this.cache.delete(cacheKey);
+            this.cache.set(cacheKey, { value, expiresAtMs: nowMs + ttlMs });
+            while (this.cache.size > WebSearchRegistryVerifier.MAX_CACHE_ENTRIES) {
+                const oldestKey = this.cache.keys().next().value;
+                if (oldestKey === undefined) {
+                    break;
+                }
+                this.cache.delete(oldestKey);
             }
-            else if (kind === "nuget") {
-                value = await this.verifyNuGet(name);
+            return value;
+        })();
+        this.inFlight.set(cacheKey, verification);
+        try {
+            return await verification;
+        }
+        finally {
+            this.inFlight.delete(cacheKey);
+        }
+    }
+    /**
+     * Reports whether one failure is a caller cancellation.
+     *
+     * @remarks
+     * Internal subfetch timeouts are reclassified as `TimeoutError` upstream
+     * and stay cacheable like any transient error; only genuine caller aborts
+     * (or errors shaped like one, e.g. a Spanish "cancelada" message) skip
+     * the error cache.
+     *
+     * @param error - Failure from a registry fetch.
+     * @param signal - Caller abort signal threaded into the verification.
+     * @returns True for caller cancellations.
+     */
+    static isCallerCancellation(error, signal) {
+        if (signal?.aborted) {
+            return true;
+        }
+        if (error instanceof Error) {
+            if (error.name === "TimeoutError" || /timeout|timed out|ETIMEDOUT/iu.test(error.message)) {
+                return false;
             }
-            else {
-                value = await this.verifyGitHub(name);
+            if (error.name === "AbortError" || /abort|cancelad/iu.test(error.message)) {
+                return true;
             }
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            value = { kind, name, status: "error", error: message };
-        }
-        this.cache.set(cacheKey, { value, expiresAtMs: nowMs + this.deps.cacheTtlMs });
-        while (this.cache.size > WebSearchRegistryVerifier.MAX_CACHE_ENTRIES) {
-            const oldestKey = this.cache.keys().next().value;
-            if (oldestKey === undefined) {
-                break;
+        return false;
+    }
+    /**
+     * Maps transport failures to stable Spanish text.
+     *
+     * @param error - Failure from a registry fetch.
+     * @returns Spanish description for the cached error entity.
+     */
+    static describeFetchError(error) {
+        if (error instanceof Error) {
+            const name = error.name;
+            const message = error.message;
+            if (name === "TimeoutError" || /timeout|timed out|ETIMEDOUT/iu.test(message)) {
+                return "Tiempo de espera agotado al consultar el registro; se reintentará en la próxima búsqueda.";
+            }
+            if (name === "AbortError" || /abort|cancelad/iu.test(message)) {
+                return "Operación cancelada antes de completar la verificación del registro.";
             }
-            this.cache.delete(oldestKey);
+            // Unknown failures (undici transport errors are English by nature,
+            // e.g. "fetch failed", "ENOTFOUND", "ECONNRESET") never reach the
+            // model raw: they are wrapped in a bounded Spanish note so
+            // `verified[].error` stays model-facing Spanish with a short
+            // technical tail.
+            const bounded = sliceUtf8Safe(message.replace(/\s+/gu, " ").trim(), 0, 120);
+            return `Fallo de red al consultar el registro (${bounded.length > 0 ? bounded : "sin detalle"}).`;
         }
-        return value;
+        const boundedRaw = sliceUtf8Safe(String(error).replace(/\s+/gu, " ").trim(), 0, 120);
+        return `Fallo de red al consultar el registro (${boundedRaw.length > 0 ? boundedRaw : "sin detalle"}).`;
     }
     /**
      * Runs tasks with a fixed concurrency limit.
@@ -213,13 +351,21 @@ export class WebSearchRegistryVerifier {
      * Verifies npm package versions via the npm registry.
      *
      * @param packageName - npm package name (may be scoped)
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyNpm(packageName) {
+    async verifyNpm(packageName, signal) {
         const encoded = encodeURIComponent(packageName);
         const sourceUrl = `https://registry.npmjs.org/${encoded}`;
-        const bodyRaw = await this.fetchJson(sourceUrl, { accept: "application/json" });
-        const body = this.tryGetRecord(bodyRaw);
+        // Popular packuments (full metadata for thousands of versions) exceed the
+        // default 5 MB cap; parity with the EnriCode client plane, which reads
+        // the same packument endpoint with a 16 MiB budget.
+        const bodyRaw = await this.httpReader.fetchJson(sourceUrl, {
+            accept: "application/json",
+            signal,
+            maxBytes: WebSearchRegistryVerifier.NPM_PACKUMENT_MAX_BYTES
+        });
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
             throw new Error(`Respuesta npm inesperada para ${sourceUrl}`);
         }
@@ -258,13 +404,14 @@ export class WebSearchRegistryVerifier {
      * Verifies PyPI project versions via the PyPI JSON API.
      *
      * @param projectName - PyPI project name
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyPyPi(projectName) {
+    async verifyPyPi(projectName, signal) {
         const encoded = encodeURIComponent(projectName);
         const sourceUrl = `https://pypi.org/pypi/${encoded}/json`;
-        const bodyRaw = await this.fetchJson(sourceUrl, { accept: "application/json" });
-        const body = this.tryGetRecord(bodyRaw);
+        const bodyRaw = await this.httpReader.fetchJson(sourceUrl, { accept: "application/json", signal });
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
             throw new Error(`Respuesta PyPI inesperada para ${sourceUrl}`);
         }
@@ -297,13 +444,14 @@ export class WebSearchRegistryVerifier {
      * Verifies crates.io package versions via the crates.io API.
      *
      * @param crateName - Crate name
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyCrates(crateName) {
+    async verifyCrates(crateName, signal) {
         const encoded = encodeURIComponent(crateName);
         const sourceUrl = `https://crates.io/api/v1/crates/${encoded}`;
-        const bodyRaw = await this.fetchJson(sourceUrl, { accept: "application/json" });
-        const body = this.tryGetRecord(bodyRaw);
+        const bodyRaw = await this.httpReader.fetchJson(sourceUrl, { accept: "application/json", signal });
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
             throw new Error(`Respuesta crates.io inesperada para ${sourceUrl}`);
         }
@@ -360,11 +508,12 @@ export class WebSearchRegistryVerifier {
      * Verifies NuGet package versions via NuGet V3 endpoints.
      *
      * @param packageId - NuGet package ID
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyNuGet(packageId) {
+    async verifyNuGet(packageId, signal) {
         const lowerId = packageId.toLowerCase();
-        const serviceIndex = await this.getNuGetServiceIndex();
+        const serviceIndex = await this.getNuGetServiceIndex(signal);
         if (!serviceIndex.packageBaseAddressUrl) {
             return {
                 kind: "nuget",
@@ -374,8 +523,8 @@ export class WebSearchRegistryVerifier {
             };
         }
         const versionsUrl = `${serviceIndex.packageBaseAddressUrl}${lowerId}/index.json`;
-        const versionsBodyRaw = await this.fetchJson(versionsUrl, { accept: "application/json" });
-        const versionsBody = this.tryGetRecord(versionsBodyRaw);
+        const versionsBodyRaw = await this.httpReader.fetchJson(versionsUrl, { accept: "application/json", signal });
+        const versionsBody = this.tryGetRecord(versionsBodyRaw.value);
         if (!versionsBody) {
             throw new Error(`Respuesta NuGet inesperada para ${versionsUrl}`);
         }
@@ -386,10 +535,10 @@ export class WebSearchRegistryVerifier {
         const bestStable = this.pickBestSemVer(versionStrings, { prerelease: false });
         const bestPre = this.pickBestSemVer(versionStrings, { prerelease: true });
         const stablePublishedAt = bestStable && serviceIndex.registrationsBaseUrl
-            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestStable)
+            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestStable, signal)
             : null;
         const prePublishedAt = bestPre && serviceIndex.registrationsBaseUrl
-            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestPre)
+            ? await this.tryFetchNuGetLeafPublishedAt(serviceIndex.registrationsBaseUrl, lowerId, bestPre, signal)
             : null;
         return {
             kind: "nuget",
@@ -406,10 +555,18 @@ export class WebSearchRegistryVerifier {
     /**
      * Verifies GitHub repository releases via GitHub REST API.
      *
+     * @remarks
+     * `latest_stable` comes from `/releases/latest` (GitHub's own newest
+     * non-prerelease, non-draft pick, immune to first-page truncation);
+     * prerelease candidates page through `/releases?per_page=100` following
+     * the `Link` header (up to {@link GITHUB_RELEASES_MAX_PAGES} pages, i.e.
+     * 300 newest releases — beyond that the first pages are what we keep).
+     *
      * @param repoSlug - Repository slug in the form "owner/repo"
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
-    async verifyGitHub(repoSlug) {
+    async verifyGitHub(repoSlug, signal) {
         const cleanSlug = repoSlug.trim().replace(/\.git$/iu, "");
         const parts = cleanSlug.split("/");
         const owner = parts[0];
@@ -417,96 +574,98 @@ export class WebSearchRegistryVerifier {
         if (!owner || !repo) {
             return { kind: "github", name: repoSlug, status: "error", error: "Repositorio inválido." };
         }
-        const sourceUrl = `https://api.github.com/repos/${owner}/${repo}/releases?per_page=100`;
-        const releasesRaw = await this.fetchJson(sourceUrl, {
-            accept: "application/vnd.github+json",
-            githubToken: this.deps.githubToken
-        });
-        const releases = Array.isArray(releasesRaw) ? releasesRaw : [];
-        const stableCandidates = [];
-        const preCandidates = [];
-        for (const item of releases) {
-            const record = this.tryGetRecord(item);
-            if (!record) {
-                continue;
-            }
-            if (record["draft"] === true) {
-                continue;
-            }
-            const tagNameRaw = this.tryGetNonEmptyString(record["tag_name"]);
-            if (!tagNameRaw) {
-                continue;
+        const latestUrl = `https://api.github.com/repos/${owner}/${repo}/releases/latest`;
+        const listUrl = `https://api.github.com/repos/${owner}/${repo}/releases?per_page=100`;
+        let latestStable = null;
+        try {
+            const latestPage = await this.httpReader.fetchJson(latestUrl, {
+                accept: "application/vnd.github+json",
+                githubToken: this.deps.githubToken,
+                signal
+            });
+            const latest = this.tryParseGitHubReleaseCandidate(latestPage.value);
+            if (latest !== null && !latest.prerelease) {
+                latestStable = { version: latest.version, publishedAt: latest.publishedAt };
             }
-            const tagName = tagNameRaw.startsWith("v") ? tagNameRaw.slice(1) : tagNameRaw;
-            const publishedAt = this.tryGetNonEmptyString(record["published_at"]);
-            const isPrerelease = record["prerelease"] === true;
-            const candidate = { version: tagName, publishedAt: publishedAt ?? null, prerelease: isPrerelease };
-            if (isPrerelease) {
-                preCandidates.push(candidate);
+        }
+        catch (error) {
+            // /releases/latest 404s when the repo has no published stable release
+            // at all; any other failure fails the entity honestly.
+            const message = error instanceof Error ? error.message : String(error);
+            if (!/HTTP 404/u.test(message)) {
+                throw error;
             }
-            else {
-                stableCandidates.push(candidate);
+        }
+        const stableListFallbacks = [];
+        const preCandidates = [];
+        let nextUrl = listUrl;
+        let fetchedPages = 0;
+        while (nextUrl !== null && fetchedPages < WebSearchRegistryVerifier.GITHUB_RELEASES_MAX_PAGES) {
+            const page = await this.httpReader.fetchJson(nextUrl, {
+                accept: "application/vnd.github+json",
+                githubToken: this.deps.githubToken,
+                signal
+            });
+            fetchedPages += 1;
+            const releases = Array.isArray(page.value) ? page.value : [];
+            for (const item of releases) {
+                const candidate = this.tryParseGitHubReleaseCandidate(item);
+                if (candidate === null) {
+                    continue;
+                }
+                if (candidate.prerelease) {
+                    preCandidates.push(candidate);
+                }
+                else {
+                    stableListFallbacks.push(candidate);
+                }
             }
+            nextUrl = page.nextUrl;
         }
-        const bestStable = this.pickBestVersionCandidate(stableCandidates, { prerelease: false });
+        const bestStable = latestStable ?? this.pickBestVersionCandidate(stableListFallbacks, { prerelease: false });
         const bestPre = this.pickBestVersionCandidate(preCandidates, { prerelease: true });
         return {
             kind: "github",
             name: repoSlug,
             latest_stable: bestStable
-                ? { version: bestStable.version, published_at: bestStable.publishedAt ?? undefined, source_url: sourceUrl }
+                ? {
+                    version: bestStable.version,
+                    published_at: bestStable.publishedAt ?? undefined,
+                    // Provenance honesty: attribute the fallback pick to the list
+                    // endpoint it actually came from, not to /releases/latest.
+                    source_url: latestStable !== null ? latestUrl : listUrl
+                }
                 : undefined,
             latest_prerelease: bestPre
-                ? { version: bestPre.version, published_at: bestPre.publishedAt ?? undefined, source_url: sourceUrl }
+                ? { version: bestPre.version, published_at: bestPre.publishedAt ?? undefined, source_url: listUrl }
                 : undefined,
             status: "ok"
         };
     }
     /**
-     * Performs an HTTP GET expecting a JSON response.
+     * Parses one GitHub release entry into a version candidate.
      *
-     * @param url - Target URL
-     * @param options - Request options
-     * @returns Parsed JSON object/array
+     * @param raw - Release entry from the GitHub API
+     * @returns Candidate, or null for drafts/entries without a tag
      */
-    async fetchJson(url, options) {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.deps.timeoutMs);
-        const headers = {
-            Accept: options.accept,
-            "User-Agent": "enriweb"
-        };
-        if (options.githubToken && options.githubToken.trim()) {
-            headers["Authorization"] = `Bearer ${options.githubToken.trim()}`;
+    tryParseGitHubReleaseCandidate(raw) {
+        const record = this.tryGetRecord(raw);
+        if (!record) {
+            return null;
         }
-        try {
-            const response = await this.deps.fetchImpl(url, {
-                method: "GET",
-                headers,
-                signal: controller.signal
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP ${String(response.status)} para ${url}`);
-            }
-            const declaredLengthRaw = response.headers.get("content-length");
-            const declaredLength = declaredLengthRaw !== null ? Number.parseInt(declaredLengthRaw, 10) : NaN;
-            if (Number.isFinite(declaredLength) && declaredLength > WebSearchRegistryVerifier.MAX_JSON_BYTES) {
-                throw new Error(`La respuesta JSON de ${url} excede el máximo de ${String(WebSearchRegistryVerifier.MAX_JSON_BYTES)} bytes.`);
-            }
-            const text = await response.text();
-            if (Buffer.byteLength(text, "utf8") > WebSearchRegistryVerifier.MAX_JSON_BYTES) {
-                throw new Error(`La respuesta JSON de ${url} excede el máximo de ${String(WebSearchRegistryVerifier.MAX_JSON_BYTES)} bytes.`);
-            }
-            try {
-                return JSON.parse(text);
-            }
-            catch {
-                throw new Error(`Respuesta no JSON del registro en ${url}.`);
-            }
+        if (record["draft"] === true) {
+            return null;
         }
-        finally {
-            clearTimeout(timeout);
+        const tagNameRaw = this.tryGetNonEmptyString(record["tag_name"]);
+        if (!tagNameRaw) {
+            return null;
         }
+        const tagName = tagNameRaw.startsWith("v") ? tagNameRaw.slice(1) : tagNameRaw;
+        return {
+            version: tagName,
+            publishedAt: this.tryGetNonEmptyString(record["published_at"]),
+            prerelease: record["prerelease"] === true
+        };
     }
     /**
      * Attempts to parse the npm package name from an npmjs.com URL.
@@ -519,7 +678,17 @@ export class WebSearchRegistryVerifier {
         if (hostname !== "www.npmjs.com" && hostname !== "npmjs.com") {
             return null;
         }
-        const segments = url.pathname.split("/").filter(Boolean);
+        const segments = url.pathname
+            .split("/")
+            .filter(Boolean)
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        });
         if (segments.length < 2 || segments[0] !== "package") {
             return null;
         }
@@ -527,6 +696,13 @@ export class WebSearchRegistryVerifier {
         if (!first) {
             return null;
         }
+        if (first.startsWith("@") && first.includes("/")) {
+            const [scope, name] = first.split("/");
+            if (!scope || !name) {
+                return null;
+            }
+            return `${scope}/${name}`;
+        }
         if (first.startsWith("@")) {
             const second = segments[2];
             if (!second) {
@@ -650,6 +826,10 @@ export class WebSearchRegistryVerifier {
     /**
      * Best-effort prerelease detection for PyPI version strings.
      *
+     * @remarks
+     * Covers PEP 440 separators and attached suffixes (`1.0b1`, `2.0beta1`)
+     * where the marker follows digits without a delimiter.
+     *
      * @param version - Version string
      * @returns True when prerelease-like
      */
@@ -661,6 +841,9 @@ export class WebSearchRegistryVerifier {
         if (/(?:^|[._-])(?:a|b|rc|dev|alpha|beta|pre|preview)\d*/.test(lower)) {
             return true;
         }
+        if (/\d(?:a|b|rc|dev|alpha|beta|pre|preview)\d*/.test(lower)) {
+            return true;
+        }
         return false;
     }
     /**
@@ -713,41 +896,86 @@ export class WebSearchRegistryVerifier {
         }
         let bestByTime = filtered[0];
         for (const item of filtered.slice(1)) {
-            if (item.publishedAt && bestByTime.publishedAt) {
-                if (item.publishedAt > bestByTime.publishedAt) {
-                    bestByTime = item;
-                }
-            }
-            else if (item.publishedAt && !bestByTime.publishedAt) {
+            const itemTime = this.tryParseTimeMs(item.publishedAt);
+            const bestTime = bestByTime !== undefined ? this.tryParseTimeMs(bestByTime.publishedAt) : null;
+            if (itemTime !== null && (bestTime === null || itemTime > bestTime)) {
                 bestByTime = item;
             }
         }
         return bestByTime;
     }
+    /**
+     * Parses one ISO timestamp to epoch milliseconds.
+     *
+     * @param value - Timestamp string, if present.
+     * @returns Epoch milliseconds, or null when missing or unparsable.
+     */
+    tryParseTimeMs(value) {
+        if (value === null || !value.trim()) {
+            return null;
+        }
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
     /**
      * Parses SemVer strings (best-effort).
      *
+     * @remarks
+     * Accepts two to four numeric components (`1.2` → `1.2.0`, `1.2.3.4`
+     * keeps the fourth as a build tiebreak) so partial registry versions
+     * still rank instead of dropping out.
+     *
      * @param raw - Version string
      * @returns Parsed semver or null
      */
     tryParseSemVer(raw) {
         const trimmed = raw.trim();
         const normalized = trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
-        const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(normalized);
+        const match = /^(\d+)\.(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(normalized);
         if (!match) {
-            return null;
+            return this.tryParseAttachedPrerelease(normalized);
         }
         const major = Number.parseInt(match[1] ?? "", 10);
         const minor = Number.parseInt(match[2] ?? "", 10);
-        const patch = Number.parseInt(match[3] ?? "", 10);
-        if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) {
+        const patch = match[3] === undefined ? 0 : Number.parseInt(match[3], 10);
+        const build = match[4] === undefined ? 0 : Number.parseInt(match[4], 10);
+        if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch) || !Number.isFinite(build)) {
             return null;
         }
-        const prereleaseRaw = match[4];
+        const prereleaseRaw = match[5];
         const prerelease = prereleaseRaw
             ? prereleaseRaw.split(".").filter((p) => p.length > 0)
             : [];
-        return { raw: normalized, major, minor, patch, prerelease };
+        return { raw: normalized, major, minor, patch, build, prerelease };
+    }
+    /**
+     * Parses versions with attached prerelease suffixes (`2024.1b1`, `2.0rc2`).
+     *
+     * @param normalized - Version string without a leading "v".
+     * @returns Parsed semver or null.
+     */
+    tryParseAttachedPrerelease(normalized) {
+        const match = /^(\d+)\.(\d+)(?:\.(\d+))?(?:\.(\d+))?(a|b|rc|alpha|beta|pre|preview|dev)(\d*)$/i.exec(normalized);
+        if (!match) {
+            return null;
+        }
+        const major = Number.parseInt(match[1] ?? "", 10);
+        const minor = Number.parseInt(match[2] ?? "", 10);
+        const patch = match[3] === undefined ? 0 : Number.parseInt(match[3], 10);
+        const build = match[4] === undefined ? 0 : Number.parseInt(match[4], 10);
+        if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch) || !Number.isFinite(build)) {
+            return null;
+        }
+        const marker = (match[5] ?? "").toLowerCase();
+        const number = match[6] ?? "";
+        return {
+            raw: normalized,
+            major,
+            minor,
+            patch,
+            build,
+            prerelease: [number ? `${marker}.${number}` : marker]
+        };
     }
     /**
      * Compares two SemVer values.
@@ -766,6 +994,9 @@ export class WebSearchRegistryVerifier {
         if (a.patch !== b.patch) {
             return a.patch - b.patch;
         }
+        if (a.build !== b.build) {
+            return a.build - b.build;
+        }
         const aPre = a.prerelease;
         const bPre = b.prerelease;
         if (aPre.length === 0 && bPre.length === 0) {
@@ -831,6 +1062,7 @@ export class WebSearchRegistryVerifier {
             return null;
         }
         let best = null;
+        let bestMs = -1;
         for (const item of releaseFiles) {
             const record = this.tryGetRecord(item);
             if (!record) {
@@ -840,8 +1072,13 @@ export class WebSearchRegistryVerifier {
             if (!uploadTime) {
                 continue;
             }
-            if (!best || uploadTime > best) {
+            const uploadMs = this.tryParseTimeMs(uploadTime);
+            if (uploadMs === null) {
+                continue;
+            }
+            if (best === null || uploadMs > bestMs) {
                 best = uploadTime;
+                bestMs = uploadMs;
             }
         }
         return best;
@@ -849,17 +1086,19 @@ export class WebSearchRegistryVerifier {
     /**
      * Resolves NuGet V3 endpoints from the service index, with caching.
      *
+     * @param signal - Optional caller abort signal
      * @returns Service index cache
      */
-    async getNuGetServiceIndex() {
+    async getNuGetServiceIndex(signal) {
         const nowMs = Date.now();
         if (this.nugetServiceIndexCache && this.nugetServiceIndexCache.expiresAtMs > nowMs) {
             return this.nugetServiceIndexCache;
         }
-        const bodyRaw = await this.fetchJson(WebSearchRegistryVerifier.NUGET_SERVICE_INDEX_URL, {
-            accept: "application/json"
+        const bodyRaw = await this.httpReader.fetchJson(WebSearchRegistryVerifier.NUGET_SERVICE_INDEX_URL, {
+            accept: "application/json",
+            signal
         });
-        const body = this.tryGetRecord(bodyRaw);
+        const body = this.tryGetRecord(bodyRaw.value);
         if (!body) {
             throw new Error("Respuesta inesperada del índice de NuGet.");
         }
@@ -907,13 +1146,14 @@ export class WebSearchRegistryVerifier {
      * @param registrationsBaseUrl - Registrations base URL
      * @param lowerId - Lowercase package ID
      * @param version - Version string
+     * @param signal - Optional caller abort signal
      * @returns Published ISO 8601 timestamp or null
      */
-    async tryFetchNuGetLeafPublishedAt(registrationsBaseUrl, lowerId, version) {
+    async tryFetchNuGetLeafPublishedAt(registrationsBaseUrl, lowerId, version, signal) {
         const leafUrl = `${registrationsBaseUrl}${lowerId}/${encodeURIComponent(version)}.json`;
         try {
-            const bodyRaw = await this.fetchJson(leafUrl, { accept: "application/json" });
-            const body = this.tryGetRecord(bodyRaw);
+            const bodyRaw = await this.httpReader.fetchJson(leafUrl, { accept: "application/json", signal });
+            const body = this.tryGetRecord(bodyRaw.value);
             if (!body) {
                 return null;
             }