@vespermcp/mcp-server 1.2.22 → 1.2.25

package/build/metadata/circuit-breaker.js

@@ -0,0 +1,62 @@
+export class CircuitBreaker {
+    name;
+    options;
+    state = "closed";
+    consecutiveFailures = 0;
+    openUntilMs = 0;
+    constructor(name, options) {
+        this.name = name;
+        this.options = options;
+    }
+    halfOpenSuccesses = 0;
+    canAttempt() {
+        if (this.state === "closed")
+            return true;
+        if (this.state === "open") {
+            if (Date.now() >= this.openUntilMs) {
+                this.state = "half_open";
+                this.halfOpenSuccesses = 0;
+                return true;
+            }
+            return false;
+        }
+        return true; // half_open
+    }
+    onSuccess() {
+        if (this.state === "half_open") {
+            this.halfOpenSuccesses++;
+            if (this.halfOpenSuccesses >= this.options.halfOpenSuccessesToClose) {
+                this.state = "closed";
+                this.consecutiveFailures = 0;
+                this.openUntilMs = 0;
+            }
+            return;
+        }
+        this.consecutiveFailures = 0;
+        this.state = "closed";
+    }
+    onFailure() {
+        if (this.state === "half_open") {
+            this.trip();
+            return;
+        }
+        this.consecutiveFailures++;
+        if (this.consecutiveFailures >= this.options.failureThreshold) {
+            this.trip();
+        }
+    }
+    trip() {
+        this.state = "open";
+        this.openUntilMs = Date.now() + this.options.openDurationMs;
+        this.consecutiveFailures = 0;
+        this.halfOpenSuccesses = 0;
+        console.error(`[CircuitBreaker] Opened: ${this.name} (until ${new Date(this.openUntilMs).toISOString()})`);
+    }
+    getStatus() {
+        return {
+            name: this.name,
+            state: this.state,
+            ...(this.state === "open" ? { open_until: new Date(this.openUntilMs).toISOString() } : {}),
+        };
+    }
+}

package/build/metadata/github-source.js

@@ -0,0 +1,228 @@
+import { rateLimitedFetch } from "./rate-limiter.js";
+import { CircuitBreaker } from "./circuit-breaker.js";
+import { estimateQualityScore } from "./quality.js";
+export class GithubSource {
+    cache;
+    breaker = new CircuitBreaker("github", {
+        failureThreshold: 5,
+        openDurationMs: 30_000,
+        halfOpenSuccessesToClose: 2,
+    });
+    constructor(cache) {
+        this.cache = cache;
+    }
+    async discover(query, limit = 20) {
+        const out = await this.discoverWithTelemetry(query, limit, { include_readme: false });
+        return out.results;
+    }
+    async discoverWithTelemetry(query, limit = 20, input = {}) {
+        const start = Date.now();
+        const cleanQuery = String(query || "").trim();
+        if (!cleanQuery) {
+            return { results: [], cacheHit: false, latencyMs: Date.now() - start, readme_fetch_ms_total: 0 };
+        }
+        const includeReadme = input.include_readme === true;
+        const perPage = Math.max(1, Math.min(100, Number(limit || 20)));
+        const cacheKey = `webcore:github:discover:${cleanQuery.toLowerCase()}:per_page=${perPage}:readme=${includeReadme ? 1 : 0}`;
+        const cached = await this.cache?.getJson(cacheKey);
+        if (cached) {
+            return { results: cached, cacheHit: true, latencyMs: Date.now() - start };
+        }
+        if (!this.breaker.canAttempt()) {
+            throw new Error("GitHub connector is temporarily unavailable (circuit open).");
+        }
+        const refinedQuery = `${cleanQuery} in:name,description,readme`;
+        const url = `https://api.github.com/search/repositories?q=${encodeURIComponent(refinedQuery)}&sort=stars&order=desc&per_page=${perPage}`;
+        const headers = {
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "vesper/2.0 (phase1-github-connector)",
+            "X-GitHub-Api-Version": "2022-11-28",
+        };
+        const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+        if (token)
+            headers["Authorization"] = `Bearer ${token}`;
+        const response = await rateLimitedFetch(url, { headers }, { maxRetries: 5, initialDelay: 1000, maxDelay: 20000 })
+            .catch((e) => {
+            // GitHub uses 403 for rate limiting; treat as breaker-worthy failure
+            this.breaker.onFailure();
+            if (String(e?.message || "").includes("403")) {
+                throw new Error("GitHub API rate limit exceeded (403). Set GITHUB_TOKEN for higher limits.");
+            }
+            throw e;
+        });
+        const data = (await response.json());
+        const items = Array.isArray(data?.items) ? data.items : [];
+        const repos = items.slice(0, perPage);
+        let readmeFetchMsTotal = 0;
+        const maxReadmes = includeReadme ? Math.min(5, repos.length) : 0;
+        const result = [];
+        for (let i = 0; i < repos.length; i++) {
+            const repo = repos[i];
+            if (includeReadme && i < maxReadmes) {
+                const fullName = String(repo.full_name || repo.name || "").trim();
+                const readmeKey = fullName ? `webcore:github:readme:${fullName}` : "webcore:github:readme:unknown";
+                const cachedReadme = await this.cache?.getJson(readmeKey);
+                if (cachedReadme) {
+                    result.push(this.toDatasetMetadata(repo, { readmeText: cachedReadme }));
+                    continue;
+                }
+                const t0 = Date.now();
+                const readmeText = await this.fetchReadme(repo).catch(() => undefined);
+                readmeFetchMsTotal += Date.now() - t0;
+                if (readmeText) {
+                    await this.cache?.setJson(readmeKey, readmeText, 21600); // 6h
+                }
+                result.push(this.toDatasetMetadata(repo, { readmeText: readmeText ? this.truncate50k(readmeText) : undefined }));
+            }
+            else {
+                result.push(this.toDatasetMetadata(repo, { readmeText: undefined }));
+            }
+        }
+        this.breaker.onSuccess();
+        await this.cache?.setJson(cacheKey, result, 21600); // 6h
+        return { results: result, cacheHit: false, latencyMs: Date.now() - start, readme_fetch_ms_total: readmeFetchMsTotal };
+    }
+    toDatasetMetadata(repo, input) {
+        const fullName = String(repo.full_name || repo.name || "unknown").trim();
+        const description = String(repo.description || "").trim() || "No description provided.";
+        const ownerRepo = this.parseOwnerRepo(fullName);
+        const owner = ownerRepo ? ownerRepo.split("/")[0] : "";
+        const stars = Number(repo.stargazers_count || 0);
+        const forks = Number(repo.forks_count || 0);
+        const updatedAt = repo.updated_at || new Date().toISOString();
+        const topics = Array.isArray(repo.topics) ? repo.topics.filter(Boolean).map(String) : [];
+        const language = repo.language ? [String(repo.language)] : [];
+        const licenseId = repo.license?.spdx_id && repo.license.spdx_id !== "NOASSERTION"
+            ? String(repo.license.spdx_id)
+            : "unknown";
+        const licenseName = repo.license?.name ? String(repo.license.name) : undefined;
+        const qualityWarnings = [];
+        if (stars < 5)
+            qualityWarnings.push("Low star count; may be low-signal");
+        if (description.length < 80)
+            qualityWarnings.push("Short description; relevance may be weaker");
+        const lowSignalPatterns = [
+            /\bawesome\b/i,
+            /\bresources?\b/i,
+            /\bcurated\b/i,
+            /\blist\b/i,
+            /\bcollection\b/i,
+        ];
+        const lowSignalText = `${fullName} ${description}`;
+        const looksResourceList = lowSignalPatterns.some((rx) => rx.test(lowSignalText));
+        if (looksResourceList) {
+            qualityWarnings.push("Repository appears to be a resource/list collection; relevance may be indirect.");
+        }
+        const abstractLength = input.readmeText ? input.readmeText.length : description.length;
+        const authorsPresent = !!owner;
+        const datePresent = !!updatedAt;
+        const contentDepth = Math.max(abstractLength, input.readmeText ? input.readmeText.length : description.length);
+        const quality01 = estimateQualityScore({
+            abstractLength,
+            authorsPresent,
+            datePresent,
+            contentDepth,
+        });
+        let adjustedQuality01 = quality01;
+        // Calibrate GitHub quality so resource-list repos don't dominate.
+        // Keep penalty moderate; readme-rich/long-form repos still score well.
+        if (looksResourceList) {
+            adjustedQuality01 -= 0.14;
+        }
+        if (!input.readmeText && description.length < 140) {
+            adjustedQuality01 -= 0.08;
+        }
+        if (stars < 50) {
+            adjustedQuality01 -= 0.04;
+        }
+        adjustedQuality01 = Math.max(0.3, Math.min(1.0, adjustedQuality01));
+        return {
+            id: fullName,
+            source: "github",
+            name: fullName.split("/").pop() || fullName,
+            description,
+            ...(owner ? { authors: [owner] } : {}),
+            downloads: forks * 10,
+            likes: stars,
+            stars,
+            tags: topics,
+            last_updated: updatedAt,
+            task: "code",
+            languages: language,
+            domain: "research",
+            splits: [],
+            license: {
+                id: licenseId,
+                name: licenseName,
+                category: "unknown",
+                usage_restrictions: [],
+                warnings: [],
+            },
+            quality_score: Math.round(adjustedQuality01 * 100),
+            quality_warnings: qualityWarnings,
+            download_url: String(repo.html_url || `https://github.com/${fullName}`),
+            format: "GIT",
+            total_examples: 1,
+            is_structured: false,
+            has_target_column: false,
+            is_safe_source: true,
+            has_personal_data: false,
+            is_paywalled: false,
+            is_scraped_web_data: false,
+            uses_https: true,
+            has_train_split: false,
+            has_test_split: false,
+            has_validation_split: false,
+            description_length: description.length,
+            has_readme: false,
+            metadata_url: String(repo.html_url || `https://github.com/${fullName}`),
+            ...(input.readmeText
+                ? { webcore_content: this.truncate50k(input.readmeText), webcore_content_kind: "readme_text" }
+                : {}),
+        };
+    }
+    truncate50k(text) {
+        return String(text || "").slice(0, 50_000);
+    }
+    parseOwnerRepo(fullName) {
+        const trimmed = String(fullName || "").trim();
+        if (trimmed.includes("/"))
+            return trimmed;
+        return null;
+    }
+    async fetchReadme(repo) {
+        const fullName = String(repo.full_name || repo.name || "").trim();
+        const ownerRepo = this.parseOwnerRepo(fullName);
+        if (!ownerRepo)
+            return undefined;
+        const [owner, name] = ownerRepo.split("/");
+        const candidates = [];
+        if (repo.default_branch)
+            candidates.push(String(repo.default_branch));
+        candidates.push("main", "master");
+        const uniq = Array.from(new Set(candidates.filter(Boolean)));
+        const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+        const headers = {
+            "User-Agent": "vesper/2.0 (phase1-github-readme)",
+            "Accept": "text/plain",
+        };
+        if (token)
+            headers["Authorization"] = `Bearer ${token}`;
+        for (const branch of uniq) {
+            const url = `https://raw.githubusercontent.com/${owner}/${name}/${branch}/README.md`;
+            const res = await fetch(url, { headers }).catch(() => null);
+            if (!res)
+                continue;
+            if (res.status === 404)
+                continue;
+            if (res.status === 429 || res.status === 403) {
+                this.breaker.onFailure();
+                throw new Error(`GitHub README fetch failed with status ${res.status}`);
+            }
+            if (!res.ok)
+                continue;
+            return await res.text();
+        }
+        return undefined;
+    }
+}

package/build/metadata/hackernews-source.js

@@ -0,0 +1,123 @@
+import { rateLimitedFetch } from "./rate-limiter.js";
+import { CircuitBreaker } from "./circuit-breaker.js";
+import { estimateQualityScore } from "./quality.js";
+export class HackerNewsSource {
+    cache;
+    breaker = new CircuitBreaker("hackernews", {
+        failureThreshold: 5,
+        openDurationMs: 30_000,
+        halfOpenSuccessesToClose: 2,
+    });
+    constructor(cache) {
+        this.cache = cache;
+    }
+    async discover(query, limit = 20) {
+        const out = await this.discoverWithTelemetry(query, limit);
+        return out.results;
+    }
+    async discoverWithTelemetry(query, limit = 20) {
+        const start = Date.now();
+        const cleanQuery = String(query || "").trim();
+        if (!cleanQuery)
+            return { results: [], cacheHit: false, latencyMs: Date.now() - start };
+        const perPage = Math.max(1, Math.min(100, Number(limit || 20)));
+        const cacheKey = `webcore:hackernews:discover:${cleanQuery.toLowerCase()}:hitsPerPage=${perPage}`;
+        const cached = await this.cache?.getJson(cacheKey);
+        if (cached)
+            return { results: cached, cacheHit: true, latencyMs: Date.now() - start };
+        if (!this.breaker.canAttempt()) {
+            throw new Error("Hacker News connector is temporarily unavailable (circuit open).");
+        }
+        const url = new URL("https://hn.algolia.com/api/v1/search");
+        url.searchParams.set("query", cleanQuery);
+        url.searchParams.set("hitsPerPage", String(perPage));
+        url.searchParams.set("page", "0");
+        const response = await rateLimitedFetch(url.toString(), {
+            headers: {
+                "Accept": "application/json",
+                "User-Agent": "vesper/2.0 (phase1-hackernews-connector)",
+            },
+        }, { maxRetries: 5, initialDelay: 750, maxDelay: 15000 }).catch((e) => {
+            this.breaker.onFailure();
+            throw e;
+        });
+        const data = await response.json().catch((e) => {
+            this.breaker.onFailure();
+            throw new Error(`Hacker News JSON parse failed: ${e?.message || String(e)}`);
+        });
+        const hits = Array.isArray(data?.hits) ? data.hits : [];
+        const result = hits.slice(0, perPage).map((h) => this.toDatasetMetadata(h));
+        this.breaker.onSuccess();
+        await this.cache?.setJson(cacheKey, result, 7200); // 2h
+        return { results: result, cacheHit: false, latencyMs: Date.now() - start };
+    }
+    toDatasetMetadata(hit) {
+        const objectID = String(hit.objectID ?? "").trim();
+        const title = String(hit.title || "").trim() || `HN item ${objectID}`;
+        const createdAt = hit.created_at ? String(hit.created_at) : new Date().toISOString();
+        const author = hit.author ? String(hit.author).trim() : "";
+        const points = Number(hit.points || 0);
+        const comments = Number(hit.num_comments || 0);
+        const storyText = String(hit.story_text || "").trim();
+        const qualityWarnings = [];
+        if (!storyText)
+            qualityWarnings.push("Missing story text in Hacker News response");
+        const abstractLength = (storyText || title).length;
+        const authorsPresent = !!author;
+        const datePresent = !!createdAt;
+        const contentDepth = abstractLength;
+        const quality01 = estimateQualityScore({
+            abstractLength,
+            authorsPresent,
+            datePresent,
+            contentDepth,
+        });
+        const itemUrl = hit.url ? String(hit.url) : (objectID ? `https://news.ycombinator.com/item?id=${objectID}` : "");
+        return {
+            id: objectID || title,
+            source: "hackernews",
+            name: title,
+            description: storyText || title,
+            authors: author ? [author] : undefined,
+            downloads: comments,
+            likes: points,
+            stars: points,
+            tags: author ? ["hackernews", `author:${author}`] : ["hackernews"],
+            last_updated: createdAt,
+            task: "thread",
+            languages: [],
+            domain: "tech",
+            splits: [],
+            license: {
+                id: "unknown",
+                category: "unknown",
+                usage_restrictions: [],
+                warnings: [],
+            },
+            quality_score: Math.round(quality01 * 100),
+            quality_warnings: qualityWarnings,
+            download_url: itemUrl,
+            format: "TEXT",
+            total_examples: 1,
+            total_size_bytes: undefined,
+            total_size_mb: undefined,
+            columns: [
+                { name: "title", type: "string" },
+                { name: "text", type: "string" },
+            ],
+            is_structured: true,
+            has_target_column: false,
+            is_safe_source: true,
+            has_personal_data: false,
+            is_paywalled: false,
+            is_scraped_web_data: false,
+            uses_https: true,
+            has_train_split: false,
+            has_test_split: false,
+            has_validation_split: false,
+            description_length: (storyText || title).length,
+            has_readme: false,
+            metadata_url: itemUrl,
+        };
+    }
+}

package/build/metadata/quality.js

@@ -46,3 +46,30 @@ export function calculateQualityScore(data) {
         score += 2;
     return Math.min(100, score);
 }
+/**
+ * Phase 1 Web Core quality estimator (document-first).
+ *
+ * Returns a score in the range [0.3, 1.0] (never 0) using weighted signals:
+ * - abstract length (text richness)
+ * - authors presence (provenance)
+ * - date presence (freshness / completeness)
+ * - content depth (optional full text / README length)
+ */
+export function estimateQualityScore(input) {
+    const abstractLen = Math.max(0, Number(input.abstractLength || 0));
+    const contentDepth = Math.max(0, Number(input.contentDepth || 0));
+    // Logistic-ish squashing: near-1 once abstract is moderately long.
+    const abstractScore = 1 / (1 + Math.exp(-(abstractLen - 200) / 120));
+    const depthScore = 1 / (1 + Math.exp(-(contentDepth - 1200) / 500));
+    const authorsScore = input.authorsPresent ? 1 : 0;
+    const dateScore = input.datePresent ? 1 : 0;
+    // Base is intentionally high so that for complete records the score clusters near 1.0.
+    const base = 0.3;
+    const score = base +
+        0.25 * abstractScore +
+        0.25 * depthScore +
+        0.1 * authorsScore +
+        0.1 * dateScore;
+    // Clamp to [0.3, 1.0]
+    return Math.max(0.3, Math.min(1.0, score));
+}

package/build/metadata/semantic-scholar-source.js

@@ -0,0 +1,138 @@
+import { rateLimitedFetch } from "./rate-limiter.js";
+import { CircuitBreaker } from "./circuit-breaker.js";
+import { estimateQualityScore } from "./quality.js";
+export class SemanticScholarSource {
+    cache;
+    breaker = new CircuitBreaker("semantic_scholar", {
+        failureThreshold: 5,
+        openDurationMs: 30_000,
+        halfOpenSuccessesToClose: 2,
+    });
+    constructor(cache) {
+        this.cache = cache;
+    }
+    async discover(query, limit = 20) {
+        const out = await this.discoverWithTelemetry(query, limit);
+        return out.results;
+    }
+    async discoverWithTelemetry(query, limit = 20) {
+        const start = Date.now();
+        const cleanQuery = String(query || "").trim();
+        if (!cleanQuery)
+            return { results: [], cacheHit: false, latencyMs: Date.now() - start };
+        const perPage = Math.max(1, Math.min(100, Number(limit || 20)));
+        const cacheKey = `webcore:semantic_scholar:discover:${cleanQuery.toLowerCase()}:limit=${perPage}`;
+        const cached = await this.cache?.getJson(cacheKey);
+        if (cached)
+            return { results: cached, cacheHit: true, latencyMs: Date.now() - start };
+        if (!this.breaker.canAttempt()) {
+            throw new Error("Semantic Scholar connector is temporarily unavailable (circuit open).");
+        }
+        const url = new URL("https://api.semanticscholar.org/graph/v1/paper/search");
+        url.searchParams.set("query", cleanQuery);
+        url.searchParams.set("limit", String(perPage));
+        url.searchParams.set("fields", [
+            "paperId",
+            "title",
+            "abstract",
+            "url",
+            "venue",
+            "year",
+            "citationCount",
+            "authors",
+            "publicationTypes",
+            "openAccessPdf",
+        ].join(","));
+        const response = await rateLimitedFetch(url.toString(), {
+            headers: {
+                "Accept": "application/json",
+                "User-Agent": "vesper/2.0 (phase1-semantic-scholar-connector)",
+            },
+        }, { maxRetries: 5, initialDelay: 1000, maxDelay: 20000 }).catch((e) => {
+            this.breaker.onFailure();
+            throw e;
+        });
+        const data = await response.json().catch((e) => {
+            this.breaker.onFailure();
+            throw new Error(`Semantic Scholar JSON parse failed: ${e?.message || String(e)}`);
+        });
+        const papers = Array.isArray(data?.data) ? data.data : [];
+        const result = papers.map((p) => this.toDatasetMetadata(p)).filter(Boolean);
+        this.breaker.onSuccess();
+        await this.cache?.setJson(cacheKey, result, 86400); // 24h
+        return { results: result, cacheHit: false, latencyMs: Date.now() - start };
+    }
+    toDatasetMetadata(paper) {
+        const paperId = String(paper.paperId || paper.externalIds?.DOI || "").trim();
+        const title = String(paper.title || "").trim();
+        const abstract = String(paper.abstract || "").trim();
+        const url = String(paper.url || "").trim();
+        const authors = Array.isArray(paper.authors) ? paper.authors.map((a) => String(a.name || "").trim()).filter(Boolean) : [];
+        const tags = [
+            ...(Array.isArray(paper.publicationTypes) ? paper.publicationTypes.filter(Boolean).map(String) : []),
+            ...(paper.venue ? [String(paper.venue)] : []),
+        ];
+        const citationCount = Number(paper.citationCount || 0);
+        const qualityWarnings = [];
+        if (!abstract)
+            qualityWarnings.push("Missing abstract from Semantic Scholar response");
+        const abstractLength = (abstract || title).length;
+        const authorsPresent = authors.length > 0;
+        const datePresent = paper.year !== undefined && paper.year !== null;
+        const contentDepth = abstractLength;
+        const quality01 = estimateQualityScore({
+            abstractLength,
+            authorsPresent,
+            datePresent,
+            contentDepth,
+        });
+        const openAccessPdfUrl = paper.openAccessPdf?.url ? String(paper.openAccessPdf.url).trim() : undefined;
+        const downloadUrl = openAccessPdfUrl || url || (paperId ? `https://www.semanticscholar.org/paper/${paperId}` : "");
+        return {
+            id: paperId || url || title,
+            source: "semantic_scholar",
+            name: title || "Untitled",
+            description: abstract || title,
+            authors,
+            downloads: 0,
+            likes: citationCount,
+            stars: citationCount,
+            tags,
+            last_updated: new Date().toISOString(),
+            task: "research-paper",
+            languages: [],
+            domain: "research",
+            splits: [],
+            license: {
+                id: "unknown",
+                category: "unknown",
+                usage_restrictions: [],
+                warnings: [],
+            },
+            quality_score: Math.round(quality01 * 100),
+            quality_warnings: qualityWarnings,
+            download_url: downloadUrl,
+            format: "PDF",
+            total_examples: 1,
+            total_size_bytes: undefined,
+            total_size_mb: undefined,
+            columns: [
+                { name: "title", type: "string" },
+                { name: "abstract", type: "string" },
+            ],
+            is_structured: true,
+            has_target_column: false,
+            is_safe_source: true,
+            has_personal_data: false,
+            is_paywalled: false,
+            is_scraped_web_data: false,
+            uses_https: true,
+            has_train_split: false,
+            has_test_split: false,
+            has_validation_split: false,
+            description_length: (abstract || title).length,
+            has_readme: false,
+            metadata_url: url || (paperId ? `https://www.semanticscholar.org/paper/${paperId}` : ""),
+        };
+    }
+}

package/build/scripts/test-phase1-webcore-quality.js

@@ -0,0 +1,104 @@
+import { CacheService, MockRedisProvider } from "../cache/service.js";
+import { ArxivSource } from "../metadata/arxiv-source.js";
+import { GithubSource } from "../metadata/github-source.js";
+import { SemanticScholarSource } from "../metadata/semantic-scholar-source.js";
+import { HackerNewsSource } from "../metadata/hackernews-source.js";
+import { WebCoreEngine } from "../web/web-core.js";
+function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.max(0, Math.ceil(p * sorted.length) - 1);
+    return sorted[idx] ?? 0;
+}
+function makeQueries() {
+    const topics = [
+        "agentic RAG evaluation",
+        "tool-augmented retrieval",
+        "LLM dataset quality scoring",
+        "semantic deduplication embeddings",
+        "cross-source dataset fusion",
+        "retrieval augmented generation metrics",
+        "dataset export parquet arrow jsonl",
+        "data safety dataset provenance",
+        "synthetic data generation alignment",
+        "multi-source corpus building",
+    ];
+    const suffixes = [
+        "paper",
+        "benchmark",
+        "latency",
+        "quality",
+        "dedup",
+        "provenance",
+        "evaluation",
+        "pipeline",
+        "MCP",
+        "agents",
+    ];
+    const out = [];
+    for (let i = 0; out.length < 100; i++) {
+        const t = topics[i % topics.length];
+        const s = suffixes[Math.floor(i / topics.length) % suffixes.length];
+        out.push(`${t} ${s}`.trim());
+    }
+    return out.slice(0, 100);
+}
+async function main() {
+    const cache = new CacheService(new MockRedisProvider());
+    const engine = new WebCoreEngine({
+        arxivSource: new ArxivSource(cache),
+        githubSource: new GithubSource(cache),
+        semanticScholarSource: new SemanticScholarSource(cache),
+        hackerNewsSource: new HackerNewsSource(cache),
+    });
+    const baseQuery = "agentic RAG evaluation";
+    const flags = { arxiv_full_text: true, github_include_readme: true };
+    const sources = ["arxiv", "github"];
+    console.log("Phase 1 Web Core validation:");
+    console.log("- Checking cached latency regression on a single query...");
+    const run1 = await engine.find({ query: baseQuery, sources: [...sources], limit: 2, ...flags });
+    const run2 = await engine.find({ query: baseQuery, sources: [...sources], limit: 2, ...flags });
+    const run2Arxiv = run2.telemetry?.per_source.find((t) => t.source === "arxiv");
+    const run2Github = run2.telemetry?.per_source.find((t) => t.source === "github");
+    console.log("Cached telemetry (run2):", {
+        arxiv: run2Arxiv ? { cache_hit: run2Arxiv.cache_hit, latency_ms: run2Arxiv.latency_ms } : null,
+        github: run2Github ? { cache_hit: run2Github.cache_hit, latency_ms: run2Github.latency_ms } : null,
+    });
+    // 100 query quality distribution test
+    console.log("- Running 100 test queries (quality distribution + extraction latency)...");
+    const queries = makeQueries();
+    const qualityScores = [];
+    const pdfExtractMs = [];
+    for (let i = 0; i < queries.length; i++) {
+        const q = queries[i];
+        const res = await engine.find({ query: q, sources: [...sources], limit: 2, ...flags });
+        for (const doc of res.results) {
+            qualityScores.push(Number(doc.quality_score));
+        }
+        const arxivTelemetry = res.telemetry?.per_source.find((t) => t.source === "arxiv");
+        if (arxivTelemetry) {
+            pdfExtractMs.push(Number(arxivTelemetry.pdf_extract_ms_total || 0));
+        }
+        if ((i + 1) % 10 === 0) {
+            console.log(`  progress: ${i + 1}/100`);
+        }
+    }
+    const q95 = percentile(qualityScores, 0.95);
+    const pdfP95 = percentile(pdfExtractMs, 0.95);
+    console.log("\nResults:");
+    console.log(`- Quality score p95: ${q95}`);
+    console.log(`- PDF extract ms p95 (arxiv): ${pdfP95}`);
+    const okQuality = q95 > 0.9;
+    const okPdfLatency = pdfP95 < 5000;
+    console.log(`\nSuccess criteria:`);
+    console.log(`- Quality p95 > 0.9: ${okQuality ? "PASS" : "FAIL"}`);
+    console.log(`- PDF extract p95 < 5000ms additional: ${okPdfLatency ? "PASS" : "FAIL"}`);
+    if (!okQuality) {
+        console.log("Tip: adjust estimateQualityScore() weights/thresholds in src/metadata/quality.ts then rerun.");
+    }
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});