@taurgis/bonsai 3.2.0 → 3.2.2

package/dist/lib/research/fetch-result.js

@@ -0,0 +1,212 @@
+import { cliErrorFields } from '../envelope.js';
+import { SANDBOX_EGRESS_ERROR_MARKER } from './browser.js';
+import { QUALITY_WARNING_PREFIX } from './extract.js';
+import { PROXY_TUNNEL_REJECTION_PATTERN } from './proxy.js';
+import { getArtifactPath } from './storage.js';
+/**
+ * Human-prose warnings pulled out of `qualityNotes` (e.g. very-short extraction). The remaining
+ * `quality:*` machine codes stay `--json`-only; this is what stderr shows in human-readable mode.
+ */
+export function extractionQualityWarnings(qualityNotes) {
+    return qualityNotes
+        .filter((note) => note.startsWith(QUALITY_WARNING_PREFIX))
+        .map((note) => note.slice(QUALITY_WARNING_PREFIX.length));
+}
+/** Remap write-implying cache statuses when dry-run/read-only skipped persistence. */
+export function reportCacheStatus(status, dryRun) {
+    if (!dryRun)
+        return status;
+    switch (status) {
+        case 'miss':
+            return 'would_fetch';
+        case 'refreshed':
+            return 'would_refresh';
+        case 'revalidated':
+            return 'would_revalidate';
+        default:
+            return status;
+    }
+}
+/** Human spinner labels for reported (possibly remapped) cache statuses. */
+export const FETCH_STATUS_LABEL = {
+    hit: 'cached',
+    miss: 'done',
+    refreshed: 'refreshed',
+    revalidated: 'revalidated',
+    stale: 'served stale',
+    would_fetch: 'previewed (not cached)',
+    would_refresh: 'previewed refresh',
+    would_revalidate: 'previewed revalidate',
+};
+/** Machine-readable success/preview payload for one fetch URL. */
+export function buildFetchResultData(input) {
+    const { artifact, format, dryRun } = input;
+    const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
+    return {
+        schemaVersion: 1,
+        command: 'fetch',
+        dryRun,
+        cache: {
+            key: input.cacheKey,
+            // Preview runs must not claim a write landed.
+            status: reportCacheStatus(input.cacheStatus, dryRun),
+            freshness: input.freshnessState,
+            path: getArtifactPath(input.storageDir, input.cacheKey),
+            storage: input.storageMode,
+            redirectedToGlobal: input.redirectedToGlobal,
+        },
+        source: {
+            url: input.url,
+            normalizedUrl: input.normalizedUrl,
+            captureMethod: artifact.metadata.capture_method,
+            extractionStatus: artifact.metadata.extraction_status,
+            extractionConfidence: artifact.metadata.extraction_confidence,
+            qualityNotes: artifact.metadata.quality_notes,
+            fetchedAt: artifact.metadata.fetched_at,
+            validatedAt: artifact.metadata.validated_at,
+            staleAfter: artifact.metadata.stale_after,
+        },
+        artifactType: artifact.metadata.artifact_type,
+        docsEngine: artifact.metadata.docs_engine,
+        docsFramework: artifact.metadata.docs_framework,
+        sourceDocUrl: artifact.metadata.source_doc_url,
+        searchProvider: artifact.metadata.search_provider,
+        format,
+        tokenEstimate: format === 'compressed'
+            ? artifact.metadata.token_estimate.compressed
+            : artifact.metadata.token_estimate.detailed,
+        content,
+    };
+}
+/** Per-URL failure row for multi-URL batches — keeps prior successes in `data`. */
+export function buildFetchFailureResult(input) {
+    const { url, dryRun, err, fallbackGuidance } = input;
+    // Prefer the throw site's suggestions/ref; otherwise attach fetch-specific recovery hints.
+    const shaped = err.suggestions?.length || err.ref ? err : { ...err, ...fallbackGuidance };
+    return {
+        schemaVersion: 1,
+        command: 'fetch',
+        dryRun,
+        error: cliErrorFields(shaped, 'FETCH_FAILED'),
+        cache: null,
+        source: { url, normalizedUrl: null },
+        content: null,
+    };
+}
+/**
+ * Shape a caught runtime error into a batch failure row (message + guidance).
+ * CLIError rows should call {@link buildFetchFailureResult} directly so oclif fields are preserved.
+ */
+export function buildFetchFailureFromCaught(bin, url, err, dryRun) {
+    const message = describeError(err);
+    return buildFetchFailureResult({
+        url,
+        dryRun,
+        err: { message, code: 'FETCH_FAILED' },
+        fallbackGuidance: fetchFailureGuidance(message, url, bin),
+    });
+}
+// How many `.cause` levels to walk. Real undici/Node transport errors nest at most 1-2 deep;
+// the cap exists so a self-referential or cyclic `.cause` chain (Error.cause is an arbitrary,
+// unvalidated property — nothing prevents `e.cause = e`, whether from a bug in this codebase or
+// a dependency) can't hang the process, rather than being a limit expected to matter in practice.
+const MAX_CAUSE_DEPTH = 10;
+// Walks an Error's `.cause` chain and joins every message, deepest last. Node/undici's fetch
+// throws a generic `TypeError: fetch failed` for transport-level failures, with the actionable
+// detail (e.g. a proxy's tunnel rejection) nested one or two `.cause` levels down.
+export function describeError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const parts = [err.message];
+    let cause = err.cause;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && cause instanceof Error; depth++) {
+        parts.push(cause.message);
+        cause = cause.cause;
+    }
+    return parts.join(': ');
+}
+// Maps a runtime fetch failure to recovery steps keyed off its message. Returns undefined for
+// unrecognized failures, which then surface with their original message and no extra hint. The
+// patterns match the thrown text in fetcher.ts/browser.ts; keep them in sync if those messages
+// change. Resolutions mirror the published troubleshooting guide.
+export function fetchFailureGuidance(message, url, bin = 'bonsai') {
+    const ref = 'https://bonsai.rhino-inquisitor.com/troubleshooting';
+    // Name the pipe step explicitly: bare `import --stdin` blocks waiting for input, so a reader (or
+    // an agent) running the hint verbatim would hang. Show the content being piped in from a file.
+    const importHint = `Open it in a browser, save the page, then import it: cat page.md | ${bin} import ${url} --stdin`;
+    // 401/403: an auth wall or anti-scraping WAF. Bonsai has no authenticated-fetch path in v1.
+    if (/failed with status 40[13]\b/.test(message)) {
+        return {
+            suggestions: ['The page requires authentication or blocks automated requests.', importHint],
+            ref,
+        };
+    }
+    if (/failed with status 404\b/.test(message)) {
+        return { suggestions: ['Check the URL is correct and the page still exists.'] };
+    }
+    if (/failed with status 5\d\d\b/.test(message)) {
+        return {
+            suggestions: ['The server returned an error. Retry later or verify the host is healthy.'],
+        };
+    }
+    // Server returned a non-HTML body (JSON, binary, or no Content-Type at all). Scope the opener to
+    // the real failure: --rendered does produce HTML, so "only scrapes HTML" would read as misleading.
+    if (/Rejected content type|does not look like HTML/.test(message)) {
+        return {
+            suggestions: [
+                'The server returned a non-HTML response (e.g. JSON or binary).',
+                'If the page is rendered by client-side JavaScript, retry with --rendered.',
+                importHint,
+            ],
+            ref,
+        };
+    }
+    if (/DNS resolution failed/.test(message)) {
+        return {
+            suggestions: ['Check the hostname is spelled correctly and resolves on a public network.'],
+        };
+    }
+    // Chrome's own network stack hit a proxy-enforced sandbox egress block (browser.ts's
+    // describeNavigationFailure already explains the cause and the fix); only a workaround and the
+    // docs ref are added here.
+    if (message.includes(SANDBOX_EGRESS_ERROR_MARKER)) {
+        return { suggestions: [importHint], ref };
+    }
+    // A configured proxy (HTTPS_PROXY/HTTP_PROXY) refused to tunnel to this host — distinct from
+    // the destination's own 401/403 above, which is the site itself rejecting the request. Shared
+    // with fetcher.ts's retry-fallback check so the two stay in sync by construction.
+    if (PROXY_TUNNEL_REJECTION_PATTERN.test(message)) {
+        return {
+            suggestions: [
+                "The configured proxy (HTTPS_PROXY/HTTP_PROXY) won't reach this host. Check its allowlist, or add the host to NO_PROXY to bypass the proxy for it.",
+                importHint,
+            ],
+            ref,
+        };
+    }
+    // The connection failed before any HTTP response was received — network-down, DNS, TLS, or a
+    // proxy issue not specifically matched above. Node/undici's fetch reports all of these as a
+    // generic "fetch failed" TypeError with no further suffix; the negative lookahead keeps this
+    // from also matching assertOk's "Fetch failed with status NNN ..." (a real HTTP response was
+    // received in that case, so it isn't a transport failure at all).
+    if (/^fetch failed\b(?!\s+with status)/i.test(message)) {
+        return {
+            suggestions: [
+                'The connection failed before a response was received. Check network connectivity and any HTTPS_PROXY/HTTP_PROXY/NO_PROXY settings.',
+                importHint,
+            ],
+            ref,
+        };
+    }
+    // A hostname that only resolves to a private/local IP at request time (literal private addresses
+    // are rejected earlier with exit 2). Blocked to prevent SSRF; only public hosts can be fetched.
+    if (/blocked local or private target/.test(message)) {
+        return {
+            suggestions: [
+                'The hostname resolves to a private or local address, which is blocked to prevent SSRF. Only public http(s) hosts can be fetched.',
+            ],
+            ref,
+        };
+    }
+    return undefined;
+}

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

@@ -1,9 +1,15 @@
+/** Optional transport limits and headers for {@link fetchStaticHtml} / {@link fetchText}. */
 export interface FetchOptions {
+    /** Abort the request after this many milliseconds. */
     timeoutMs?: number;
+    /** Maximum response body size in bytes. */
     bodyLimitBytes?: number;
+    /** Maximum number of HTTP redirects to follow. */
     maxRedirects?: number;
+    /** Extra request headers (e.g. conditional-request validators). */
     headers?: Record<string, string>;
 }
+/** Successful or not-modified HTTP fetch result used by capture and revalidation. */
 export interface FetchResult {
     status: number;
     contentType: string | null;
@@ -13,17 +19,49 @@ export interface FetchResult {
     responseSize: number;
     content: string;
 }
+/** The fetched-page fields artifact building consumes — FetchResult minus the transport status. */
+export type FetchedContent = Omit<FetchResult, 'status'>;
+/**
+ * Heuristic: body looks like HTML/XML when `Content-Type` is missing.
+ *
+ * @param text - Response body text.
+ * @returns `true` when the trimmed body starts with a common HTML/XML marker.
+ */
 export declare function looksLikeHtml(text: string): boolean;
+/**
+ * Resolve a hostname and reject private/loopback targets.
+ * May skip local DNS when only a proxy can resolve the host.
+ *
+ * @param hostname - Host to check (IPv6 literals may be bracketed).
+ * @throws {Error} When the resolved address is not safe to fetch.
+ */
 export declare function checkDnsSafety(hostname: string): Promise<void>;
-export declare function fetchStaticHtml(url: string, options?: FetchOptions): Promise<FetchResult>;
 /**
- * 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.
+ * True when `err` is the static fetcher's own content-type policy rejection (non-HTML body or
+ * content-type), as opposed to a transient failure (network error, timeout, HTTP error status).
+ * The caller uses this to distinguish "this URL fundamentally isn't a web page" — where an
+ * automatic rendered-browser retry would just render Chrome's built-in JSON/PDF viewer and produce
+ * a corrupted-looking "extracted" artifact — from "this page may need JavaScript", where retrying
+ * rendered is the whole point of the fallback.
  */
-export declare function fetchText(url: string, options?: FetchOptions): Promise<FetchResult>;
+export declare function isUnsupportedContentTypeError(err: unknown): boolean;
 /**
- * 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.
+ * Fetch an HTML page with DNS, redirect, timeout, and body-size safety.
+ *
+ * @param url - Absolute URL to fetch.
+ * @param options - Optional timeout, body limit, redirect cap, and headers.
+ * @returns Fetch result including body content and validator headers.
+ * @throws {Error} On unsafe DNS, non-HTML content, HTTP failure, or redirect limits.
  */
-export declare function postJson(url: string, body: unknown, headers?: Record<string, string>, options?: FetchOptions): Promise<string>;
+export declare function fetchStaticHtml(url: string, options?: FetchOptions): Promise<FetchResult>;
+/**
+ * Fetch a non-HTML text/data resource (llms.txt, route Markdown, search index) with the same
+ * DNS, redirect, timeout, and body-size safety as {@link fetchStaticHtml}. Does not enforce a
+ * content type; the caller must validate the returned body is the artifact kind it expected.
+ *
+ * @param url - Absolute URL to fetch.
+ * @param options - Optional timeout, body limit, redirect cap, and headers.
+ * @returns Fetch result including body text and validator headers.
+ * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
+ */
+export declare function fetchText(url: string, options?: FetchOptions): Promise<FetchResult>;

package/dist/lib/research/fetcher.js

@@ -3,6 +3,11 @@ import { isIP } from 'node:net';
 import { fetch as undiciFetch } from 'undici';
 import { isSafeIp, normalizeUrl } from './url.js';
 import { getProxyDispatcher, isProxyConfigured, PROXY_TUNNEL_REJECTION_PATTERN } from './proxy.js';
+const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+const DEFAULT_BODY_LIMIT_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_REDIRECTS = 5;
+const HTTP_NOT_MODIFIED = 304;
+const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
 // Runs one fetch attempt with its own fresh AbortController/timeout, so that when `doFetch` makes
 // a second attempt (the proxy fallback below) it gets the full timeout budget rather than
 // whatever was left over from the first attempt's signal. Loosely typed at this one boundary
@@ -56,6 +61,12 @@ async function doFetch(url, init, timeoutMs) {
         return fetchWithTimeout(fetch, url, init, timeoutMs);
     }
 }
+/**
+ * Heuristic: body looks like HTML/XML when `Content-Type` is missing.
+ *
+ * @param text - Response body text.
+ * @returns `true` when the trimmed body starts with a common HTML/XML marker.
+ */
 export function looksLikeHtml(text) {
     const trimmed = text.trimStart().toLowerCase();
     return (trimmed.startsWith('<!doctype html') ||
@@ -63,6 +74,13 @@ export function looksLikeHtml(text) {
         trimmed.startsWith('<xml') ||
         trimmed.startsWith('<?xml'));
 }
+/**
+ * Resolve a hostname and reject private/loopback targets.
+ * May skip local DNS when only a proxy can resolve the host.
+ *
+ * @param hostname - Host to check (IPv6 literals may be bracketed).
+ * @throws {Error} When the resolved address is not safe to fetch.
+ */
 export async function checkDnsSafety(hostname) {
     let hostToResolve = hostname;
     if (hostToResolve.startsWith('[') && hostToResolve.endsWith(']')) {
@@ -128,15 +146,32 @@ function headerMeta(res) {
 }
 // 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: '' };
+    return {
+        status: HTTP_NOT_MODIFIED,
+        ...headerMeta(res),
+        finalUrl: currentUrl,
+        responseSize: 0,
+        content: '',
+    };
 }
 function assertOk(res) {
     if (!res.ok) {
         throw new Error(`Fetch failed with status ${res.status} ${res.statusText}`);
     }
 }
+/**
+ * True when `err` is the static fetcher's own content-type policy rejection (non-HTML body or
+ * content-type), as opposed to a transient failure (network error, timeout, HTTP error status).
+ * The caller uses this to distinguish "this URL fundamentally isn't a web page" — where an
+ * automatic rendered-browser retry would just render Chrome's built-in JSON/PDF viewer and produce
+ * a corrupted-looking "extracted" artifact — from "this page may need JavaScript", where retrying
+ * rendered is the whole point of the fallback.
+ */
+export function isUnsupportedContentTypeError(err) {
+    return err instanceof Error && /^Rejected /.test(err.message);
+}
 async function processFetchResponse(res, limit, currentUrl) {
-    if (res.status === 304)
+    if (res.status === HTTP_NOT_MODIFIED)
         return notModifiedResult(res, currentUrl);
     assertOk(res);
     const contentType = res.headers.get('content-type');
@@ -163,7 +198,7 @@ async function processFetchResponse(res, limit, currentUrl) {
 // 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)
+    if (res.status === HTTP_NOT_MODIFIED)
         return notModifiedResult(res, currentUrl);
     assertOk(res);
     const bodyBytes = await readBodyWithLimit(res.body, limit);
@@ -178,9 +213,9 @@ async function processTextResponse(res, limit, currentUrl) {
 // 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 timeout = options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    const limit = options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
     const initialHeaders = options.headers ?? {};
     let currentUrl = normalizeUrl(url);
     let redirectCount = 0;
@@ -188,7 +223,7 @@ async function fetchWithRedirects(url, options, process) {
         const parsedUrl = new URL(currentUrl);
         await checkDnsSafety(parsedUrl.hostname);
         const res = await doFetch(currentUrl, { method: 'GET', headers: initialHeaders, redirect: 'manual' }, timeout);
-        if ([301, 302, 303, 307, 308].includes(res.status)) {
+        if (REDIRECT_STATUS_CODES.has(res.status)) {
             redirectCount++;
             if (redirectCount > maxRedirects) {
                 throw new Error(`Too many redirects. Exceeded limit of ${maxRedirects}.`);
@@ -203,34 +238,27 @@ async function fetchWithRedirects(url, options, process) {
         return await process(res, limit, currentUrl);
     }
 }
+/**
+ * Fetch an HTML page with DNS, redirect, timeout, and body-size safety.
+ *
+ * @param url - Absolute URL to fetch.
+ * @param options - Optional timeout, body limit, redirect cap, and headers.
+ * @returns Fetch result including body content and validator headers.
+ * @throws {Error} On unsafe DNS, non-HTML content, HTTP failure, or redirect limits.
+ */
 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.
+ * Fetch a non-HTML text/data resource (llms.txt, route Markdown, search index) with the same
+ * DNS, redirect, timeout, and body-size safety as {@link fetchStaticHtml}. Does not enforce a
+ * content type; the caller must validate the returned body is the artifact kind it expected.
+ *
+ * @param url - Absolute URL to fetch.
+ * @param options - Optional timeout, body limit, redirect cap, and headers.
+ * @returns Fetch result including body text and validator headers.
+ * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
  */
 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 res = await doFetch(target, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', ...headers },
-        body: JSON.stringify(body),
-        redirect: 'error',
-    }, timeout);
-    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);
-}

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

@@ -1,29 +1,72 @@
 import type { ResearchArtifactMetadata } from './schema.js';
+/** Fresh and grace windows derived from a tier and optional TTL override. */
 export interface FreshnessPolicy {
     freshWindowMs: number;
     graceWindowMs: number;
 }
 /**
- * Parses simple TTL duration strings to milliseconds. The unit `m` is months (not minutes); the
- * smallest unit is hours, since sub-hour cache lifespans are not meaningful for research artifacts.
+ * Parses a TTL/duration string into milliseconds.
+ * The unit `m` means months (not minutes); the smallest unit is hours.
+ *
+ * @param ttl - Whole number plus unit (`h`/`d`/`w`/`m`/`y`).
+ * @returns Duration in milliseconds.
+ * @throws {Error} When the format is invalid or the duration is zero.
  */
 export declare function parseTtlToMs(ttl: string): number;
 /**
- * Validate a duration-valued flag. Returns an actionable error message that names the
- * offending flag when the value is malformed, or null when the flag is absent or valid.
- * Callers map a non-null message onto `this.error(msg, { exit: 2 })`, so every command
- * reports the same parse failure while naming the exact flag the user passed.
+ * Validate a duration-valued flag.
+ *
+ * @param flag - Flag token for the error message (e.g. `--ttl`).
+ * @param value - Raw flag value, or `undefined` when omitted.
+ * @returns Actionable error message, or `null` when absent/valid.
  */
 export declare function durationFlagError(flag: string, value: string | undefined): string | null;
 /**
- * Derives the active freshness policy based on the tier and optional TTL override.
+ * Derives the active freshness policy from a tier and optional TTL override.
+ * When a TTL override is set, grace scales proportionally to the tier's default ratio.
+ *
+ * @param tier - Freshness tier (`stable` / `standard` / `volatile`).
+ * @param ttlOverride - Optional TTL string replacing the tier's fresh window.
+ * @returns Fresh and grace windows in milliseconds.
  */
-export declare function getPolicy(tier: 'stable' | 'standard' | 'volatile', ttlOverride?: string | null): FreshnessPolicy;
+export declare function resolveFreshnessPolicy(tier: 'stable' | 'standard' | 'volatile', ttlOverride?: string | null): FreshnessPolicy;
 /**
  * Evaluates the freshness status of a cached artifact.
+ * `ttlOverride` / `tierOverride` let status (and similar read-only checks) evaluate "what if"
+ * policies without mutating the stored metadata. When omitted, the artifact's own tier/TTL win.
+ *
+ * @param meta - Artifact metadata providing timestamps, tier, and stored TTL.
+ * @param currentTime - Clock used for age calculation.
+ * @param ttlOverride - Optional TTL replacing the stored TTL for this evaluation.
+ * @param tierOverride - Optional tier replacing the stored tier for this evaluation.
+ * @returns `fresh`, `stale_grace`, or `stale_expired`.
  */
-export declare function evaluateFreshness(meta: ResearchArtifactMetadata, currentTime: Date, ttlOverride?: string | null): 'fresh' | 'stale_grace' | 'stale_expired';
+export declare function evaluateFreshness(meta: ResearchArtifactMetadata, currentTime: Date, ttlOverride?: string | null, tierOverride?: 'stable' | 'standard' | 'volatile' | null): 'fresh' | 'stale_grace' | 'stale_expired';
 /**
- * Checks if the cached entry's age exceeds the specified max-age duration.
+ * Checks whether the cached entry's age exceeds the specified max-age duration.
+ *
+ * @param cached - Artifact (or metadata bag) with fetch/validate timestamps.
+ * @param currentTime - Clock used for age calculation.
+ * @param maxAge - Duration string, or `undefined` to skip the check.
+ * @returns `true` when max-age is set and exceeded.
  */
-export declare function checkMaxAgeExpired(cached: any, currentTime: Date, maxAge: string | undefined): boolean;
+export declare function checkMaxAgeExpired(cached: {
+    metadata: Pick<ResearchArtifactMetadata, 'fetched_at' | 'validated_at'>;
+}, currentTime: Date, maxAge: string | undefined): boolean;
+/**
+ * Freshness for a cached artifact, applying `--max-age` before the tier/TTL windows.
+ *
+ * @param cached - Artifact with full metadata.
+ * @param currentTime - Clock used for age calculation.
+ * @param options.ttl - Optional TTL override.
+ * @param options.maxAge - Optional max-age duration; when exceeded returns `stale_expired`.
+ * @param options.tier - Optional tier override.
+ * @returns `fresh`, `stale_grace`, or `stale_expired`.
+ */
+export declare function evaluateFreshnessWithMaxAge(cached: {
+    metadata: ResearchArtifactMetadata;
+}, currentTime: Date, options?: {
+    ttl?: string | null;
+    maxAge?: string;
+    tier?: 'stable' | 'standard' | 'volatile' | null;
+}): 'fresh' | 'stale_grace' | 'stale_expired';