@taurgis/bonsai 1.0.0

package/dist/lib/research/fetcher.js

@@ -0,0 +1,192 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { isSafeIp, normalizeUrl } from './url.js';
+export function looksLikeHtml(text) {
+    const trimmed = text.trimStart().toLowerCase();
+    return (trimmed.startsWith('<!doctype html') ||
+        trimmed.startsWith('<html') ||
+        trimmed.startsWith('<xml') ||
+        trimmed.startsWith('<?xml'));
+}
+export async function checkDnsSafety(hostname) {
+    let hostToResolve = hostname;
+    if (hostToResolve.startsWith('[') && hostToResolve.endsWith(']')) {
+        hostToResolve = hostToResolve.slice(1, -1);
+    }
+    if (isIP(hostToResolve) !== 0) {
+        if (!isSafeIp(hostToResolve)) {
+            throw new Error(`IP address "${hostToResolve}" is a blocked local or private target.`);
+        }
+        return;
+    }
+    try {
+        const addresses = await lookup(hostToResolve, { all: true });
+        for (const addr of addresses) {
+            if (!isSafeIp(addr.address)) {
+                throw new Error(`IP address "${addr.address}" resolved for "${hostname}" is a blocked local or private target.`);
+            }
+        }
+    }
+    catch (err) {
+        throw new Error(`DNS resolution failed for hostname "${hostname}": ${err.message}`);
+    }
+}
+async function readBodyWithLimit(body, limit) {
+    if (!body) {
+        return new Uint8Array(0);
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of body) {
+        const chunkBytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+        totalBytes += chunkBytes.byteLength;
+        if (totalBytes > limit) {
+            throw new Error(`Response body size limit exceeded. Limit is ${limit} bytes.`);
+        }
+        chunks.push(chunkBytes);
+    }
+    const result = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+// Shared response metadata. Both the HTML and text processors build their FetchResult from these
+// same validator headers, so reading them in one place keeps the two paths from drifting.
+function headerMeta(res) {
+    return {
+        contentType: res.headers.get('content-type'),
+        etag: res.headers.get('etag'),
+        lastModified: res.headers.get('last-modified'),
+    };
+}
+// A 304 carries no body; return an empty result that preserves the validator headers.
+function notModifiedResult(res, currentUrl) {
+    return { status: 304, ...headerMeta(res), finalUrl: currentUrl, responseSize: 0, content: '' };
+}
+function assertOk(res) {
+    if (!res.ok) {
+        throw new Error(`Fetch failed with status ${res.status} ${res.statusText}`);
+    }
+}
+async function processFetchResponse(res, limit, currentUrl) {
+    if (res.status === 304)
+        return notModifiedResult(res, currentUrl);
+    assertOk(res);
+    const contentType = res.headers.get('content-type');
+    if (contentType) {
+        const cleanType = (contentType.split(';')[0] || '').toLowerCase().trim();
+        if (cleanType !== 'text/html' && cleanType !== 'application/xhtml+xml') {
+            throw new Error(`Rejected content type "${contentType}". Only HTML is supported.`);
+        }
+    }
+    const bodyBytes = await readBodyWithLimit(res.body, limit);
+    const content = new TextDecoder().decode(bodyBytes);
+    if (!contentType && !looksLikeHtml(content)) {
+        throw new Error('Rejected response: missing Content-Type and body does not look like HTML.');
+    }
+    return {
+        status: res.status,
+        ...headerMeta(res),
+        finalUrl: currentUrl,
+        responseSize: bodyBytes.byteLength,
+        content,
+    };
+}
+// Processes a non-HTML response (llms.txt, route .md, search index JSON). Mirrors the safety of
+// processFetchResponse (304, status, size limit) but does NOT reject by content type — the caller
+// validates that the body is the artifact kind it asked for. Treated as untrusted text.
+async function processTextResponse(res, limit, currentUrl) {
+    if (res.status === 304)
+        return notModifiedResult(res, currentUrl);
+    assertOk(res);
+    const bodyBytes = await readBodyWithLimit(res.body, limit);
+    return {
+        status: res.status,
+        ...headerMeta(res),
+        finalUrl: currentUrl,
+        responseSize: bodyBytes.byteLength,
+        content: new TextDecoder().decode(bodyBytes),
+    };
+}
+// Shared redirect/DNS/timeout loop. The `process` callback decides how to validate and shape the
+// final (non-redirect) response, so HTML and text/data fetches reuse identical transport safety.
+async function fetchWithRedirects(url, options, process) {
+    const timeout = options.timeoutMs ?? 10_000;
+    const limit = options.bodyLimitBytes ?? 2 * 1024 * 1024;
+    const maxRedirects = options.maxRedirects ?? 5;
+    const initialHeaders = options.headers ?? {};
+    let currentUrl = normalizeUrl(url);
+    let redirectCount = 0;
+    while (true) {
+        const parsedUrl = new URL(currentUrl);
+        await checkDnsSafety(parsedUrl.hostname);
+        const controller = new AbortController();
+        const id = setTimeout(() => controller.abort(), timeout);
+        try {
+            const res = await fetch(currentUrl, {
+                method: 'GET',
+                headers: initialHeaders,
+                redirect: 'manual',
+                signal: controller.signal,
+            });
+            if ([301, 302, 303, 307, 308].includes(res.status)) {
+                redirectCount++;
+                if (redirectCount > maxRedirects) {
+                    throw new Error(`Too many redirects. Exceeded limit of ${maxRedirects}.`);
+                }
+                const location = res.headers.get('location');
+                if (!location) {
+                    throw new Error(`Redirect response status ${res.status} missing Location header.`);
+                }
+                currentUrl = normalizeUrl(new URL(location, currentUrl).toString());
+                continue;
+            }
+            return await process(res, limit, currentUrl);
+        }
+        finally {
+            clearTimeout(id);
+        }
+    }
+}
+export async function fetchStaticHtml(url, options = {}) {
+    return fetchWithRedirects(url, options, processFetchResponse);
+}
+/**
+ * Fetches a non-HTML text/data resource (llms.txt, route Markdown, search index) with the same
+ * DNS, redirect, timeout, and body-size safety as fetchStaticHtml. Does not enforce a content
+ * type; the caller must validate the returned body is the artifact kind it expected.
+ */
+export async function fetchText(url, options = {}) {
+    return fetchWithRedirects(url, options, processTextResponse);
+}
+/**
+ * Sends a JSON POST and returns the response body text. Used by remote search connectors (e.g.
+ * Algolia DocSearch). Enforces the same DNS safety, timeout, and body-size limits as GET fetches.
+ */
+export async function postJson(url, body, headers = {}, options = {}) {
+    const timeout = options.timeoutMs ?? 10_000;
+    const limit = options.bodyLimitBytes ?? 2 * 1024 * 1024;
+    const target = normalizeUrl(url);
+    await checkDnsSafety(new URL(target).hostname);
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeout);
+    try {
+        const res = await fetch(target, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify(body),
+            redirect: 'error',
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            throw new Error(`Search request failed with status ${res.status} ${res.statusText}`);
+        const bytes = await readBodyWithLimit(res.body, limit);
+        return new TextDecoder().decode(bytes);
+    }
+    finally {
+        clearTimeout(id);
+    }
+}

package/dist/lib/research/freshness.d.ts

@@ -0,0 +1,21 @@
+import type { ResearchArtifactMetadata } from './schema.js';
+export interface FreshnessPolicy {
+    freshWindowMs: number;
+    graceWindowMs: number;
+}
+/**
+ * Parses simple TTL duration strings (e.g. '24h', '7d', '30d') to milliseconds.
+ */
+export declare function parseTtlToMs(ttl: string): number;
+/**
+ * Derives the active freshness policy based on the tier and optional TTL override.
+ */
+export declare function getPolicy(tier: 'stable' | 'standard' | 'volatile', ttlOverride?: string | null): FreshnessPolicy;
+/**
+ * Evaluates the freshness status of a cached artifact.
+ */
+export declare function evaluateFreshness(meta: ResearchArtifactMetadata, currentTime: Date, ttlOverride?: string | null): 'fresh' | 'stale_grace' | 'stale_expired';
+/**
+ * Checks if the cached entry's age exceeds the specified max-age duration.
+ */
+export declare function checkMaxAgeExpired(cached: any, currentTime: Date, maxAge: string | undefined): boolean;

package/dist/lib/research/freshness.js

@@ -0,0 +1,82 @@
+/**
+ * Parses simple TTL duration strings (e.g. '24h', '7d', '30d') to milliseconds.
+ */
+export function parseTtlToMs(ttl) {
+    const match = ttl.match(/^(\d+)([hdwmy])$/);
+    if (!match) {
+        throw new Error(`Invalid TTL format "${ttl}". Use formats like '24h', '7d', '30d'.`);
+    }
+    const val = parseInt(match[1] || '', 10);
+    const unit = match[2] || '';
+    const hour = 3600 * 1000;
+    const day = 24 * hour;
+    switch (unit) {
+        case 'h':
+            return val * hour;
+        case 'd':
+            return val * day;
+        case 'w':
+            return val * 7 * day;
+        case 'm':
+            return val * 30 * day;
+        case 'y':
+            return val * 365 * day;
+        default:
+            return 0;
+    }
+}
+/**
+ * Derives the active freshness policy based on the tier and optional TTL override.
+ */
+export function getPolicy(tier, ttlOverride) {
+    const day = 24 * 3600 * 1000;
+    let freshWindowMs = 30 * day;
+    let graceWindowMs = 14 * day;
+    if (tier === 'stable') {
+        freshWindowMs = 180 * day;
+        graceWindowMs = 60 * day;
+    }
+    else if (tier === 'volatile') {
+        freshWindowMs = 7 * day;
+        graceWindowMs = 5 * day;
+    }
+    const activeTtl = ttlOverride;
+    if (activeTtl) {
+        freshWindowMs = parseTtlToMs(activeTtl);
+        const defaultFresh = tier === 'stable' ? 180 * day : tier === 'volatile' ? 7 * day : 30 * day;
+        const defaultGrace = tier === 'stable' ? 60 * day : tier === 'volatile' ? 5 * day : 14 * day;
+        graceWindowMs = Math.floor(freshWindowMs * (defaultGrace / defaultFresh));
+    }
+    return { freshWindowMs, graceWindowMs };
+}
+/**
+ * Evaluates the freshness status of a cached artifact.
+ */
+export function evaluateFreshness(meta, currentTime, ttlOverride) {
+    const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
+    const validated = meta.validated_at ? new Date(meta.validated_at).getTime() : 0;
+    const baseTime = Math.max(fetched, validated);
+    const { freshWindowMs, graceWindowMs } = getPolicy(meta.tier, ttlOverride || meta.ttl);
+    const ageMs = currentTime.getTime() - baseTime;
+    if (ageMs <= freshWindowMs) {
+        return 'fresh';
+    }
+    if (ageMs <= freshWindowMs + graceWindowMs) {
+        return 'stale_grace';
+    }
+    return 'stale_expired';
+}
+/**
+ * Checks if the cached entry's age exceeds the specified max-age duration.
+ */
+export function checkMaxAgeExpired(cached, currentTime, maxAge) {
+    if (!maxAge)
+        return false;
+    const fetched = cached.metadata.fetched_at ? new Date(cached.metadata.fetched_at).getTime() : 0;
+    const validated = cached.metadata.validated_at
+        ? new Date(cached.metadata.validated_at).getTime()
+        : 0;
+    const baseTime = Math.max(fetched, validated);
+    const ageMs = currentTime.getTime() - baseTime;
+    return ageMs > parseTtlToMs(maxAge);
+}

package/dist/lib/research/markdown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Converts HTML content to clean, deterministic Markdown.
+ * Configured to use ATX-style headings (#) and fenced code blocks (```), with GFM tables.
+ */
+export declare function dropEmptyLinks(markdown: string): string;
+export declare function htmlToMarkdown(html: string): string;

package/dist/lib/research/markdown.js

@@ -0,0 +1,66 @@
+import TurndownService from 'turndown';
+// Cell text must survive as a single Markdown table cell: collapse internal whitespace (newlines
+// from block children would split the row) and escape pipes (an unescaped `|` adds phantom columns).
+function tableCellText(node) {
+    return (node.textContent || '').replace(/\s+/g, ' ').trim().replace(/\|/g, '\\|');
+}
+function rowCells(tr) {
+    return Array.from(tr.children).map(tableCellText);
+}
+// A table's own rows are direct <tr> children or rows inside its direct <thead>/<tbody>/<tfoot>.
+// Walking the structure (rather than querySelectorAll('tr')) excludes rows of tables nested inside
+// a cell, which would otherwise be absorbed as phantom rows of the outer table.
+function ownRows(table) {
+    const rows = [];
+    for (const child of Array.from(table.children)) {
+        const tag = child.tagName.toLowerCase();
+        if (tag === 'tr')
+            rows.push(child);
+        else if (tag === 'thead' || tag === 'tbody' || tag === 'tfoot') {
+            for (const row of Array.from(child.children)) {
+                if (row.tagName.toLowerCase() === 'tr')
+                    rows.push(row);
+            }
+        }
+    }
+    return rows;
+}
+// Turndown core ships no table rule (it emits the cells as run-together text). The canonical
+// turndown-plugin-gfm is unmaintained and escapes neither pipes nor newlines in cells, so we add a
+// small self-contained GFM rule: first <tr> is the header, ragged rows are padded, cells sanitized.
+function addGfmTableRule(service) {
+    service.addRule('gfmTable', {
+        filter: 'table',
+        replacement: (_content, node) => {
+            const matrix = ownRows(node)
+                .map(rowCells)
+                .filter((cells) => cells.length > 0);
+            const [header, ...body] = matrix;
+            if (!header)
+                return '';
+            const columns = Math.max(header.length, ...body.map((cells) => cells.length));
+            const pad = (cells) => [...cells, ...Array(columns - cells.length).fill('')];
+            const line = (cells) => `| ${pad(cells).join(' | ')} |`;
+            const separator = `| ${Array(columns).fill('---').join(' | ')} |`;
+            return ['', line(header), separator, ...body.map(line), ''].join('\n');
+        },
+    });
+}
+/**
+ * Converts HTML content to clean, deterministic Markdown.
+ * Configured to use ATX-style headings (#) and fenced code blocks (```), with GFM tables.
+ */
+// Icon-only/empty anchors (e.g. a heading's "#" permalink, a ReadMe query-param chip) convert to a
+// text-less link `[](url)` that carries no information and just wastes tokens. Drop them, but never
+// match images `![](url)` (empty alt is still a real image).
+export function dropEmptyLinks(markdown) {
+    return markdown.replace(/(?<!!)\[\s*\]\([^)]*\)/g, '');
+}
+export function htmlToMarkdown(html) {
+    const turndownService = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+    });
+    addGfmTableRule(turndownService);
+    return dropEmptyLinks(turndownService.turndown(html));
+}

package/dist/lib/research/regression.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Canonicalizes a Salesforce docs CDN asset URL by replacing its volatile version segment with a
+ * placeholder, so a baseline doesn't churn every time the CDN bumps an asset version. Any other
+ * host (e.g. react.dev, tanstack.com) is returned unchanged.
+ */
+export declare function normalizeRegressionAssetUrl(rawUrl: string): string;
+/** Normalizes volatile bits of rendered Markdown so regression diffs reflect real content drift. */
+export declare function normalizeRegressionMarkdown(markdown: string): string;
+export interface ContentMetrics {
+    chars: number;
+    codeBlocks: number;
+    tables: number;
+    images: number;
+    orderedSteps: number;
+    bullets: number;
+    headings: number;
+}
+/**
+ * Structural content signals used to catch information loss between baseline and current output:
+ * a sudden drop in code blocks, tables, images, or steps flags that a fetch change dropped content.
+ */
+export declare function contentMetrics(markdown: string): ContentMetrics;
+export declare function leakageSignals(markdown: string): string[];

package/dist/lib/research/regression.js

@@ -0,0 +1,93 @@
+// Helpers for the live regression suite (testing/regression). Kept here as pure, unit-tested
+// functions so the suite runner stays a thin orchestration script and the comparison logic is
+// covered by the normal test run.
+const SALESFORCE_DOCS_IMAGE_HOST = 'sf-zdocs-cdn-prod.zoominsoftware.com';
+const SALESFORCE_DOCS_IMAGE_VERSION = '__asset_version__';
+const UUID_SEGMENT = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Canonicalizes a Salesforce docs CDN asset URL by replacing its volatile version segment with a
+ * placeholder, so a baseline doesn't churn every time the CDN bumps an asset version. Any other
+ * host (e.g. react.dev, tanstack.com) is returned unchanged.
+ */
+export function normalizeRegressionAssetUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return rawUrl;
+    }
+    if (url.hostname !== SALESFORCE_DOCS_IMAGE_HOST)
+        return rawUrl;
+    const segments = url.pathname.split('/').filter(Boolean);
+    // Expect /<version>/.../images/...; only rewrite when the version segment is a UUID.
+    if (segments.length < 3 ||
+        !segments.includes('images') ||
+        !UUID_SEGMENT.test(segments[1] ?? '')) {
+        return rawUrl;
+    }
+    segments[1] = SALESFORCE_DOCS_IMAGE_VERSION;
+    return `${url.protocol}//${url.host}/${segments.join('/')}${url.search}${url.hash}`;
+}
+/** Normalizes volatile bits of rendered Markdown so regression diffs reflect real content drift. */
+export function normalizeRegressionMarkdown(markdown) {
+    return markdown
+        .replace(/https:\/\/sf-zdocs-cdn-prod\.zoominsoftware\.com\/[^\s)]+/g, normalizeRegressionAssetUrl)
+        .replace(/\r\n/g, '\n')
+        .replace(/[ \t]+$/gm, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/**
+ * Structural content signals used to catch information loss between baseline and current output:
+ * a sudden drop in code blocks, tables, images, or steps flags that a fetch change dropped content.
+ */
+export function contentMetrics(markdown) {
+    return {
+        chars: markdown.length,
+        codeBlocks: Math.floor((markdown.match(/```/g) || []).length / 2),
+        tables: (markdown.match(/^\|(?:\s*---\s*\|)+\s*$/gm) || []).length,
+        images: (markdown.match(/!\[[^\]]*\]\(/g) || []).length,
+        orderedSteps: (markdown.match(/^\d+\.\s+/gm) || []).length,
+        bullets: (markdown.match(/^[-*]\s+/gm) || []).length,
+        headings: (markdown.match(/^#{1,6}\s+/gm) || []).length,
+    };
+}
+// Noise patterns that should NOT survive extraction into the cached Markdown. Each leaked match
+// wastes agent tokens (raw chrome, nav menus, theme widgets, app-shell placeholders). Kept separate
+// from contentMetrics because these are "too much", not "too little".
+const LEAKAGE_PATTERNS = [
+    // Genuine page-chrome HTML surviving Turndown: structural chrome tags, or ANY tag carrying a
+    // class/id/role/aria attribute (the signature of a UI element, not a code-example tag like a bare
+    // <button>/<label> in JSX). Code blocks are already excluded by stripCode().
+    {
+        label: 'raw-html',
+        re: /<(?:nav|header|footer|aside|svg|path)\b|<[a-z][a-z0-9]*\s[^>]*\b(?:class|id|role|aria-[a-z]+)\s*=/i,
+    },
+    { label: 'base64-image', re: /data:image\/[a-z]+;base64,/i },
+    { label: 'skip-to-content', re: /skip to (?:main )?content/i },
+    { label: 'on-this-page', re: /^on this page$/im },
+    { label: 'theme-toggle', re: /(?:toggle|switch to) (?:dark|light|the)? ?(?:mode|theme)/i },
+    {
+        label: 'cookie-consent',
+        re: /(?:accept all cookies|we use cookies|cookie (?:policy|preferences|settings))/i,
+    },
+    { label: 'loading-shell', re: /^\s*loading[.…]*\s*$/im },
+    { label: 'search-placeholder', re: /^\s*search(?:\.{3}|…|\s+docs)?\s*$/im },
+    // Text-less anchor links carry no content and only waste tokens (icon/permalink leftovers).
+    { label: 'empty-link', re: /(?<!!)\[\s*\]\([^)]*\)/ },
+    // Unrendered template/KumaScript macros, e.g. {{jsxref("…")}} or {{EmbedInteractiveExample(…)}}.
+    // Function-call form only, so Vue/Angular `{{ count }}` interpolation is never flagged.
+    { label: 'template-macro', re: /\{\{\s*[A-Za-z]\w*\s*\(/ },
+];
+function stripFenced(markdown) {
+    return markdown.replace(/```[\s\S]*?```/g, '').replace(/~~~[\s\S]*?~~~/g, '');
+}
+// Most leak checks must ignore code entirely (a Vue/HTML snippet is not chrome). The empty-link
+// check is the exception: stripping inline code would turn a real `[`code`](url)` link into a
+// bogus `[](url)`, so it scans with inline code intact (only fenced blocks removed).
+export function leakageSignals(markdown) {
+    const fenced = stripFenced(markdown);
+    const noCode = fenced.replace(/`[^`]*`/g, '');
+    return LEAKAGE_PATTERNS.filter(({ label, re }) => re.test(label === 'empty-link' ? fenced : noCode)).map(({ label }) => label);
+}

package/dist/lib/research/resolve-target.d.ts

@@ -0,0 +1,18 @@
+import { type LocatedArtifact } from './storage.js';
+import { type StoreRoots } from './store-roots.js';
+import type { StorageMode } from '../config/index.js';
+export interface ResolveResearchTargetOptions {
+    configDir: string | undefined;
+    cwd: string;
+    dataDir: string;
+    flagOverride?: StorageMode;
+    lookup?: boolean;
+    url: string;
+}
+export interface ResolvedResearchTarget {
+    cacheKey: string;
+    located: LocatedArtifact | null;
+    normalizedUrl: string;
+    roots: StoreRoots;
+}
+export declare function resolveResearchTarget(opts: ResolveResearchTargetOptions): ResolvedResearchTarget;

package/dist/lib/research/resolve-target.js

@@ -0,0 +1,20 @@
+import { deriveCacheKey } from './cache-key.js';
+import { locateArtifact } from './storage.js';
+import { loadStoreRoots } from './store-roots.js';
+import { normalizeUrl } from './url.js';
+export function resolveResearchTarget(opts) {
+    const normalizedUrl = normalizeUrl(opts.url);
+    const cacheKey = deriveCacheKey(normalizedUrl);
+    const roots = loadStoreRoots({
+        configDir: opts.configDir,
+        cwd: opts.cwd,
+        dataDir: opts.dataDir,
+        flagOverride: opts.flagOverride,
+    });
+    return {
+        cacheKey,
+        located: opts.lookup === false ? null : locateArtifact(roots.readRoots, cacheKey),
+        normalizedUrl,
+        roots,
+    };
+}

package/dist/lib/research/revalidate.d.ts

@@ -0,0 +1,32 @@
+import type { ResearchArtifact } from './schema.js';
+export interface RevalidationResult {
+    status: 'revalidated' | 'refreshed' | 'stale';
+    artifact: ResearchArtifact;
+    allowed?: boolean;
+    error?: string;
+}
+/**
+ * Helper to construct a ResearchArtifact from a fresh HTML fetch.
+ */
+export declare function createArtifactFromFetch(url: string, normalizedUrl: string, cacheKey: string, fetchResult: {
+    contentType: string | null;
+    etag: string | null;
+    lastModified: string | null;
+    finalUrl: string;
+    responseSize: number;
+    content: string;
+}, extraction: {
+    title: string;
+    detailedMarkdown: string;
+    confidence: 'high' | 'medium' | 'low';
+    qualityNotes: string[];
+}, tier: 'stable' | 'standard' | 'volatile', ttl: string | null, currentTime: Date): ResearchArtifact;
+/**
+ * Revalidates a stale cache artifact using conditional request headers,
+ * falling back to stale serving within the grace period if the remote host is offline.
+ */
+export declare function revalidateCache(dataDir: string, existing: ResearchArtifact, currentTime: Date, options: {
+    allowStale: boolean;
+    ttlOverride?: string | null;
+    rendered?: boolean;
+}): Promise<RevalidationResult>;