@forkpoint/agent-lighthouse-core 1.0.0 → 3.0.0

package/dist/index.d.mts

@@ -6,11 +6,28 @@ interface FetchOptions {
     timeout?: number;
     followRedirects?: boolean;
     acceptHeader?: string;
-    method?: 'GET' | 'POST' | 'OPTIONS' | 'HEAD';
+    method?: 'GET' | 'POST' | 'OPTIONS' | 'HEAD' | 'DELETE';
     body?: string;
     contentType?: string;
+    /** Override the User-Agent header (e.g. to probe a site as a specific AI bot). */
+    userAgent?: string;
+    /**
+     * Extra request headers (e.g. `MCP-Protocol-Version`). Applied before the
+     * fetcher's own headers, so a caller can add headers but cannot clobber the
+     * scanner User-Agent, the negotiated Accept, or credentials lifted out of the
+     * URL's userinfo.
+     */
+    headers?: Record<string, string>;
     /** External abort (e.g. the per-scan deadline). Combined with the per-request timeout. */
     signal?: AbortSignal;
+    /**
+     * Read the response as bytes instead of text.
+     *
+     * `body` is a UTF-8 decoded string, which replaces every invalid sequence
+     * with U+FFFD — fatal for an image, whose provenance metadata is binary. With
+     * this flag the response arrives in `bytes` and `body` stays empty.
+     */
+    binary?: boolean;
 }
 interface FetchResult {
     url: string;
@@ -22,6 +39,21 @@ interface FetchResult {
     totalMs: number;
     contentType: string;
     contentLength: number;
+    /** Raw response bytes. Present only when the request asked for `binary`. */
+    bytes?: Uint8Array;
+    /**
+     * Every redirect hop the fetcher walked, in order. Absent when the caller
+     * disabled redirects or the response was not a redirect.
+     *
+     * `finalUrl` alone cannot say whether a host change was permanent. A scan
+     * has to tell a domain migration (301/308) from a temporary hop to somebody
+     * else's domain, so the status of each hop is kept.
+     */
+    redirectChain?: Array<{
+        status: number;
+        from: string;
+        to: string;
+    }>;
     error?: string;
 }
 /**
@@ -35,10 +67,20 @@ declare function createFetcher(): {
 
 interface WafProtection {
     isBlocked: boolean;
-    provider?: 'akamai' | 'cloudflare' | 'datadome' | 'perimeterx' | 'imperva' | 'kasada' | 'aws-waf' | 'generic-waf' | 'connection-drop';
+    provider?: 'akamai' | 'cloudflare' | 'datadome' | 'perimeterx' | 'imperva' | 'kasada' | 'aws-waf' | 'generic-waf' | 'connection-drop' | 'rate-limited';
     name: string;
     reason: string;
     statusCode?: number;
+    /**
+     * The scan was throttled, not refused.
+     *
+     * An HTTP 429 says "too many requests", which is a statement about this
+     * scan's request rate and not about who the site admits. An audit that
+     * cannot tell the two apart must not report a bot wall on the strength of
+     * one — a storefront that serves GPTBot perfectly well would be told its
+     * firewall is blocking AI crawlers.
+     */
+    isRateLimit?: boolean;
 }
 /**
  * Analyzes fetch results (homepage, root files, extra pages) to determine
@@ -89,13 +131,23 @@ interface AuditGuidance {
     tags?: string[];
 }
 type ScoreDisplayMode = 'binary' | 'ternary' | 'informative';
-/** Public sunset notice for a deprecated audit (see docs/evidence/sunset/NOT-A-FACTOR.md). */
+/** Public sunset notice for a deprecated audit (see docs/evidence/sunset/not-a-factor.md). */
 interface DeprecationNotice {
     /** One sentence: why this signal is not a factor. */
     notice: string;
-    /** Public rationale URL (NOT-A-FACTOR.md anchor). */
+    /** Public rationale URL (not-a-factor.md anchor). */
     link: string;
 }
+/**
+ * Strength of the published evidence backing an audit, assigned in the audit's
+ * dossier per docs/evidence/policy.md. Only A and B carry scoring weight.
+ */
+type EvidenceGrade = 'A' | 'B' | 'C' | 'D';
+/**
+ * How an audit participates in scoring. Derived from its evidence grade
+ * (spec §4): only `scored` audits move a category score.
+ */
+type AuditTier = 'scored' | 'informative' | 'experimental';
 interface AuditMeta {
     id: string;
     category: string;
@@ -109,7 +161,31 @@ interface AuditMeta {
     guidance?: AuditGuidance;
     /** Present when the audit is sunset: shown as a notice, excluded from scores. */
     deprecated?: DeprecationNotice;
+    /** Evidence grade from the audit's dossier (docs/evidence/policy.md). */
+    evidenceGrade?: EvidenceGrade;
+    /** Scoring tier derived from the grade (spec §4). */
+    tier?: AuditTier;
+    /** Repo-relative path to the audit's evidence dossier. */
+    dossier?: string;
+    /**
+     * Which classes of scan evidence this audit needs to say anything true.
+     *
+     * Declared per audit rather than inferred at runtime, and checked against
+     * what the source actually reads by `scripts/check-requires.mjs`. An audit
+     * that reads the sampled pages — directly or through a page-fed gatherer —
+     * needs all four keys; one that reads only root files needs the origin to
+     * have answered. The deliberate disagreements are the audits whose subject
+     * *is* the missing evidence, and they are listed in that script.
+     */
+    requires?: EvidenceKey[];
 }
+/**
+ * A class of evidence a scan either obtained or did not.
+ *
+ * Declared here rather than in `scan-evidence.ts` so `AuditMeta` can name it
+ * without the audit layer importing the scan layer.
+ */
+type EvidenceKey = 'origin-reachable' | 'unblocked-fetches' | 'rendered-body' | 'sample-adequate';
 interface AuditResult {
     status: CheckStatus;
     score: number;
@@ -126,6 +202,13 @@ interface AuditResult {
     };
     pageUrl?: string;
     priority?: CheckPriority;
+    /**
+     * A fix written from what this scan actually found.
+     *
+     * Overrides `meta.guidance.fix` in the report, so an audit can name the
+     * offending section rather than repeat the generic advice.
+     */
+    remediation?: string;
 }
 type CheckStatus = 'pass' | 'warn' | 'fail' | 'na';
 type CheckPriority = 'critical' | 'high' | 'medium' | 'low';
@@ -142,6 +225,8 @@ interface CheckResult {
     description: string;
     status: CheckStatus;
     score: number;
+    /** Evidence-derived weight copied from AuditMeta.weight (A=1.0, B=0.6, informative=0). */
+    weight?: number;
     scoreDisplayMode: ScoreDisplayMode;
     displayValue?: string;
     explanation?: string;
@@ -154,11 +239,17 @@ interface CheckResult {
         found?: string;
         code?: string;
         docsUrl?: string;
+        /** The published evidence dossier for this check, derived from its id. */
+        evidenceUrl?: string;
         [key: string]: unknown;
     };
     tags?: string[];
     /** Present when the audit is sunset: shown as a notice, excluded from scores. */
     deprecated?: DeprecationNotice;
+    /** Evidence grade copied from AuditMeta.evidenceGrade. */
+    evidenceGrade?: EvidenceGrade;
+    /** Scoring tier copied from AuditMeta.tier. */
+    tier?: AuditTier;
 }
 interface CategoryResult {
     id: string;
@@ -171,12 +262,31 @@ interface CategoryResult {
     failCount: number;
 }
 type ScoreTier = 'agent-ready' | 'partially-ready' | 'needs-work' | 'not-ready';
+/**
+ * Whether a verdict about this site can mean anything, and what is missing.
+ *
+ * A scan that fetched nothing still produced a number before this existed:
+ * `ridge.com` scored 43 and `westontable.com` 37 on scans that read no page,
+ * against a real store's 51. The numbers overlap, so a reader could not
+ * separate "mediocre site" from "we never saw this site". When `judgeable` is
+ * false the report carries no score at all — not a zero, not a low number.
+ */
+interface ScanValidity {
+    judgeable: boolean;
+    evidence: Record<EvidenceKey, boolean>;
+    reasons: Partial<Record<EvidenceKey, string>>;
+    /** Why the score was suppressed, when it was. */
+    unscoredReason?: string;
+}
 interface ScanReport {
     scanId: string;
     url: string;
     domain: string;
-    overallScore: number;
-    scoreTier: ScoreTier;
+    /** Null when the scan obtained too little evidence to judge the site. */
+    overallScore: number | null;
+    /** Null exactly when `overallScore` is. */
+    scoreTier: ScoreTier | null;
+    scanValidity?: ScanValidity;
     summary?: string;
     categories: CategoryResult[];
     topPasses: CheckResult[];
@@ -209,89 +319,38 @@ interface ReadinessVitals {
     technical: number;
 }
 
-type PhaseId = 'fetch-root' | 'fetch-pages' | 'analyze' | 'audits' | 'report';
-type ScanEvent = {
-    type: 'scan:start';
-    url: string;
-    fraction: number;
-    elapsedMs: number;
-} | {
-    type: 'phase:start';
-    phase: PhaseId;
-    totalUnits: number;
-    fraction: number;
-    elapsedMs: number;
-} | {
-    type: 'unit:done';
-    phase: PhaseId;
-    completed: number;
-    total: number;
-    label?: string;
-    fraction: number;
-    elapsedMs: number;
-} | {
-    type: 'unit:fail';
-    phase: PhaseId;
-    label: string;
-    error: string;
-    fraction: number;
-    elapsedMs: number;
-} | {
-    type: 'phase:done';
-    phase: PhaseId;
-    durationMs: number;
-    fraction: number;
-    elapsedMs: number;
-} | {
-    type: 'scan:done';
-    durationMs: number;
-    score: number;
-    fraction: number;
-    elapsedMs: number;
-};
-/**
- * How much of the overall scan fraction each phase owns. Sums to 1 so the
- * fraction of a finished scan is exactly 1.
- */
-declare const PHASE_WEIGHTS: Record<PhaseId, number>;
 /**
- * Turns scan milestones into {@link ScanEvent}s. Owns the fraction math
- * (`Σ weights of done phases + current phase weight × completed/total`),
- * clamps it to be monotonic non-decreasing, and stamps `fraction`/`elapsedMs`
- * onto every event. Emission is synchronous — throttling is a consumer concern.
+ * What a scan actually obtained, decided once, before any audit runs.
+ *
+ * An audit that runs on evidence the scan never got reports a verdict about
+ * the scanner, not about the site: "no structured data" when the fetch was
+ * refused, "0 words" when the origin never answered. This module names the
+ * classes of evidence a scan can be missing so those audits can be skipped
+ * with the reason attached instead of answering blind.
+ *
+ * Pure: no network, no IO. It reads what the orchestrator already has.
  */
-declare class ProgressTracker {
-    private readonly onEvent;
-    private readonly startMs;
-    private doneWeight;
-    private phase;
-    private phaseStartMs;
-    private totalUnits;
-    private completedUnits;
-    private lastFraction;
-    constructor(onEvent: (event: ScanEvent) => void);
-    /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
-    get fraction(): number;
-    /** Stamp an event with the current fraction/elapsed and advance the floor. */
-    private stamp;
-    private elapsedMs;
-    scanStart(url: string): void;
-    phaseStart(phase: PhaseId, totalUnits: number): void;
-    /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
-    setPhaseTotal(totalUnits: number): void;
-    unitDone(label?: string): void;
-    /** A failed unit still counts as settled work so the phase can complete. */
-    unitFail(label: string, error: string): void;
-    phaseDone(): void;
-    scanDone(score: number): void;
-}
 
-interface ScanOptions {
-    onEvent?: (event: ScanEvent) => void;
-    pages?: PageOverride[] | null;
-    signal?: AbortSignal;
+interface ScanEvidence {
+    met: Record<EvidenceKey, boolean>;
+    /** One sentence per unmet key, shown in the `na` stub and the trace. */
+    reasons: Partial<Record<EvidenceKey, string>>;
+    /** Page URL to "the served HTML carried text a non-JS consumer can read". */
+    renderedByPage: Record<string, boolean>;
+    usablePageTypes: Set<PageType>;
+    /** False when no verdict about this site can mean anything. */
+    judgeable: boolean;
 }
-declare function runScan(url: string, options?: ScanOptions): Promise<ScanReport>;
+interface ScanEvidenceInput {
+    requestedUrl: string;
+    homepageResult: FetchResult;
+    pages: PageContext[];
+    rootFiles: Record<string, FetchResult>;
+    wafProtection: WafProtection | null;
+}
+declare function buildScanEvidence(input: ScanEvidenceInput): ScanEvidence;
+/** All requirements met. For test harnesses not exercising the gate. */
+declare function allEvidenceMet(): ScanEvidence;
 
 interface A11yNodeFinding {
     target: string;
@@ -340,9 +399,25 @@ interface CheckContext {
     baseUrl: string;
     fetch: (options: FetchOptions) => Promise<FetchResult>;
     wafProtection?: WafProtection;
+    /**
+     * What the scan actually obtained, decided once before any audit ran.
+     *
+     * Required, not optional. An optional field fails open, and a caller that
+     * forgets is exactly the silent-nothing verdict this exists to remove. Test
+     * harnesses that do not exercise the gate pass `allEvidenceMet()`.
+     */
+    evidence: ScanEvidence;
 }
 type CheckFn = (ctx: CheckContext) => CheckResult | Promise<CheckResult>;
 
+/**
+ * Where an audit's evidence dossier is published. A pure function of the id.
+ *
+ * Every audit id is `<category>/<slug>`, and the documentation site publishes
+ * one page per dossier at that path with a trailing slash (`trailingSlash:
+ * 'always'`), so no per-audit field is needed to reach the evidence.
+ */
+declare function evidenceUrl(id: string): string;
 /**
  * Base class for all audits. Follows the Lighthouse pattern:
  * each audit is a class with a static `meta` descriptor and
@@ -351,6 +426,16 @@ type CheckFn = (ctx: CheckContext) => CheckResult | Promise<CheckResult>;
 declare abstract class Audit {
     static meta: AuditMeta;
     private static readonly PRIORITY_MAP;
+    /**
+     * Split the fourth argument of `fail`/`warn` into a priority and a fix.
+     *
+     * The argument started as a priority token and grew a second use: audits
+     * pass a sentence describing the fix for what this scan found. A sentence is
+     * not a `CheckPriority`, and putting it there made `toCheckResult` throw on
+     * the schema — so a sentence is read as the remediation and the priority
+     * falls back to the audit's default.
+     */
+    private static splitRecommendation;
     /** Validate an audit result against the schema. */
     protected validate(result: AuditResult): AuditResult;
     /** Run the audit and return a result. */
@@ -381,7 +466,11 @@ declare abstract class Audit {
 interface CategoryConfig {
     id: string;
     name: string;
-    /** Weight in the overall score (all weights should sum to 1.0). */
+    /**
+     * Evidence mass: the summed weight of the category's registered audits
+     * (spec §4). Relative, not a percentage — `calculateOverallScore` normalizes
+     * by the total mass, so a category with no scored audits weighs nothing.
+     */
     weight: number;
 }
 interface AuditRegistration {
@@ -395,7 +484,77 @@ interface ScanConfig {
     /** categoryId → list of audit registrations */
     audits: Record<string, AuditRegistration[]>;
 }
+/**
+ * Evidence mass per category: Σ of the member audits' weights (spec §4).
+ *
+ * This replaces the old hand-tuned `CATEGORY_WEIGHTS` map. A category earns
+ * influence over the overall score by carrying proven audits, so moving an
+ * audit between categories moves its mass with it and nothing else changes.
+ * Categories made entirely of informative/experimental audits have mass 0 and
+ * cannot move the overall score.
+ */
+declare const CATEGORY_MASS: Record<string, number>;
 declare const defaultConfig: ScanConfig;
+/** Every registered category id, in canonical report order. */
+declare const CATEGORY_IDS: readonly string[];
+/**
+ * Narrow a scan to a subset of the registry.
+ *
+ * Two independent filters: `categories` restricts which categories run at all,
+ * and `includeExperimental` decides whether experimental-tier audits are part
+ * of the run. Experimental audits are excluded unless asked for — they carry
+ * weight 0 either way, but running an unvalidated check on every scan is a
+ * decision the operator makes, not a default.
+ *
+ * Returns the same object when there is nothing to filter, so the common path
+ * allocates nothing.
+ */
+declare function filterConfig(config: ScanConfig, opts: {
+    categories?: string[];
+    includeExperimental?: boolean;
+}): ScanConfig;
+
+/**
+ * What one audit did, in a form that can be diffed.
+ *
+ * A report says what an audit concluded. Tracing bad logic needs more: which
+ * audits never ran and why, how long each took, and what evidence each verdict
+ * was drawn from. That is the difference between "this site failed
+ * `faqpage-schema`" and "`faqpage-schema` ran in 4ms against 0 sampled pages",
+ * and only the second one tells you where to look.
+ *
+ * One record per registered audit, every scan, no exceptions — an audit that
+ * crashed or was skipped is exactly the one worth seeing.
+ */
+interface AuditTrace {
+    id: string;
+    category: string;
+    /**
+     * `ran` — the audit executed and returned.
+     * `skipped` — no scanned page matched its `applicablePageTypes`.
+     * `gated` — the scan never obtained evidence the audit needs.
+     * `error` — it threw, or its result was rejected by the schema.
+     */
+    outcome: 'ran' | 'skipped' | 'gated' | 'error';
+    status: CheckStatus;
+    score: number;
+    weight: number;
+    tier?: string;
+    evidenceGrade?: string;
+    /** Wall time inside `audit()`. Zero for an audit that never ran. */
+    durationMs: number;
+    displayValue?: string;
+    explanation?: string;
+    pageUrl?: string;
+    /** The structured evidence behind the verdict, as the report carries it. */
+    details?: CheckResult['details'];
+}
+/** Which outcome a finished check represents. */
+declare function outcomeOf(check: CheckResult): AuditTrace['outcome'];
+/** Build a trace record from a finished check. */
+declare function traceFromCheck(check: CheckResult, durationMs: number): AuditTrace;
+/** One trace as a log line: the shape a human scans, not the full record. */
+declare function formatTrace(trace: AuditTrace): string;
 
 interface AuditRunResult {
     checks: CheckResult[];
@@ -414,6 +573,14 @@ type AuditProgressEvent = {
     label: string;
     error: string;
 };
+/**
+ * Called once per registered audit, with what it did.
+ *
+ * Separate from {@link AuditProgressEvent}, which exists to drive a progress
+ * bar and carries only a label. This carries the verdict and its evidence, and
+ * fires for skipped and errored audits too — those are the ones worth seeing.
+ */
+type AuditTraceHandler = (trace: AuditTrace) => void;
 interface AuditPlan {
     runnable: Array<{
         reg: AuditRegistration;
@@ -421,23 +588,402 @@ interface AuditPlan {
     }>;
     skipped: CheckResult[];
 }
+/** How `planAudits` should treat audits the scan cannot feed. */
+interface PlanOptions {
+    /**
+     * Skip audits whose `requires` the scan did not obtain.
+     *
+     * Off by default while the gate is calibrated: turning it on changes what
+     * every blocked or client-rendered scan reports, and that lands as one
+     * deliberate change rather than as a side effect of this one.
+     */
+    enforceEvidence?: boolean;
+}
 /**
  * Split a scan config into the audits that will actually execute and the
- * page-type-skipped `na` stubs. Exported so the orchestrator can size the
+ * `na` stubs for those it will not. Exported so the orchestrator can size the
  * audits progress phase before running it.
  */
-declare function planAudits(ctx: CheckContext, config: ScanConfig): AuditPlan;
+declare function planAudits(ctx: CheckContext, config: ScanConfig, options?: PlanOptions): AuditPlan;
 /**
  * Execute all audits registered in the config against the scan context.
  * Returns check results grouped into categories with weighted scores.
  * Pass a precomputed `plan` (from {@link planAudits}) to avoid recomputing it.
  */
-declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan): Promise<AuditRunResult>;
+declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan, onTrace?: AuditTraceHandler): Promise<AuditRunResult>;
+
+type PhaseId = 'fetch-root' | 'fetch-pages' | 'analyze' | 'audits' | 'report';
+type ScanEvent = {
+    type: 'scan:start';
+    url: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:start';
+    phase: PhaseId;
+    totalUnits: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:done';
+    phase: PhaseId;
+    completed: number;
+    total: number;
+    label?: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:fail';
+    phase: PhaseId;
+    label: string;
+    error: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:done';
+    phase: PhaseId;
+    durationMs: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'scan:done';
+    durationMs: number;
+    /** Null when the scan obtained too little evidence to judge the site. */
+    score: number | null;
+    fraction: number;
+    elapsedMs: number;
+};
+/**
+ * How much of the overall scan fraction each phase owns. Sums to 1 so the
+ * fraction of a finished scan is exactly 1.
+ */
+declare const PHASE_WEIGHTS: Record<PhaseId, number>;
+/**
+ * Turns scan milestones into {@link ScanEvent}s. Owns the fraction math
+ * (`Σ weights of done phases + current phase weight × completed/total`),
+ * clamps it to be monotonic non-decreasing, and stamps `fraction`/`elapsedMs`
+ * onto every event. Emission is synchronous — throttling is a consumer concern.
+ */
+declare class ProgressTracker {
+    private readonly onEvent;
+    private readonly startMs;
+    private doneWeight;
+    private phase;
+    private phaseStartMs;
+    private totalUnits;
+    private completedUnits;
+    private lastFraction;
+    constructor(onEvent: (event: ScanEvent) => void);
+    /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
+    get fraction(): number;
+    /** Stamp an event with the current fraction/elapsed and advance the floor. */
+    private stamp;
+    private elapsedMs;
+    scanStart(url: string): void;
+    phaseStart(phase: PhaseId, totalUnits: number): void;
+    /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
+    setPhaseTotal(totalUnits: number): void;
+    unitDone(label?: string): void;
+    /** A failed unit still counts as settled work so the phase can complete. */
+    unitFail(label: string, error: string): void;
+    phaseDone(): void;
+    scanDone(score: number | null): void;
+}
+
+interface ScanOptions {
+    onEvent?: (event: ScanEvent) => void;
+    pages?: PageOverride[] | null;
+    signal?: AbortSignal;
+    /**
+     * Restrict the scan to these category ids. Unknown ids simply match nothing —
+     * validate them at the entry point so the operator hears about a typo.
+     */
+    categories?: string[];
+    /**
+     * Include audits whose tier is `experimental`. Off by default, per
+     * docs/evidence/policy.md: an experimental check is behind a flag and never
+     * scored.
+     */
+    includeExperimental?: boolean;
+    /**
+     * Called once per registered audit with what it did — including the ones
+     * that were skipped or failed. Use it to trace a verdict back to the
+     * evidence it was drawn from; see {@link AuditTrace}.
+     */
+    onAuditTrace?: AuditTraceHandler;
+    /**
+     * Skip audits the scan could not feed, instead of running them blind.
+     *
+     * On by default. An audit whose required evidence the scan never obtained
+     * reports `na` tagged `skipped:no-evidence`, with the reason attached, and
+     * is never constructed. Set it to `false` to run every audit regardless —
+     * useful when measuring what the gate removes.
+     */
+    enforceEvidenceGate?: boolean;
+}
+declare function runScan(url: string, options?: ScanOptions): Promise<ScanReport>;
+
+type FetchClass = 'ok' | 'soft-404' | 'blocked' | 'missing' | 'error';
+type ExpectedKind = 'text' | 'json' | 'xml' | 'html';
+declare function stripBom(text: string): string;
+declare function normalizeNewlines(text: string): string;
+/**
+ * Classify a fetched root file honestly. `status === 200` alone is not
+ * "the file exists": SPAs and some CDNs return the HTML app shell (200)
+ * for any unknown path — a soft 404 that inflated v1 scores.
+ *
+ * The body is the primary evidence and outranks the Content-Type header. Plenty
+ * of real servers ship `/llms.txt` or `/sitemap.xml` as `text/html`; trusting
+ * the header there would condemn a genuine file as a soft 404.
+ */
+declare function classifyFetch(result: FetchResult | undefined, expected: ExpectedKind): FetchClass;
+declare function isRealFile(result: FetchResult | undefined, expected: ExpectedKind): boolean;
+
+interface RobotsRule {
+    type: 'allow' | 'disallow';
+    path: string;
+}
+interface RobotsGroup {
+    userAgent: string;
+    rules: RobotsRule[];
+    crawlDelay?: number;
+    /**
+     * Directives inside the group that are neither rules nor crawl-delay, in file
+     * order — Content-Signal, Request-rate, vendor extensions. Retained rather
+     * than dropped: a directive we do not model today is still evidence about
+     * what the operator declared. Absent when the group carries none.
+     */
+    otherDirectives?: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/** A parsed robots.txt: its groups plus the file-level directives outside them. */
+interface RobotsFile {
+    groups: RobotsGroup[];
+    /**
+     * Every `Sitemap:` value, in file order. RFC 9309 §2.2.3 makes this directive
+     * host-global and user-agent independent: it is not part of any group, which
+     * is exactly why a site can advertise a sitemap its own rules forbid.
+     */
+    sitemaps: string[];
+}
+/**
+ * Parse robots.txt into groups plus file-level directives.
+ *
+ * `parseRobots` returns this function's `groups` and nothing else, so the
+ * group-only view every existing audit uses and the whole-file view added for
+ * the Plan 5 discovery audits can never disagree about grouping.
+ */
+declare function parseRobotsFile(body: string): RobotsFile;
+declare function parseRobots(body: string): RobotsGroup[];
+/** Group UA "GPTBot/1.1" matches bot token "gptbot": compare the product token. */
+declare function matchesUserAgent(groupUserAgent: string, botToken: string): boolean;
+/**
+ * Does this bot have a group of its own?
+ *
+ * Under RFC 9309 §2.2.1 a crawler obeys the most specific matching group and
+ * ignores `*` entirely once a named group exists. So "the wildcard allows it"
+ * is not an answer for a bot with its own group, and this predicate is what
+ * lets an audit report which set of rules actually applied.
+ */
+declare function hasNamedGroup(groups: RobotsGroup[], botToken: string): boolean;
+declare function groupsForBot(groups: RobotsGroup[], botToken: string): RobotsGroup[];
+declare function isPathAllowed(groups: RobotsGroup[], botToken: string, path: string): boolean;
+declare function isBlanketBlocked(groups: RobotsGroup[], botToken: string): boolean;
+
+/**
+ * The AI crawlers whose published User-Agent strings can actually be sent.
+ *
+ * `Google-Extended` is deliberately absent: it is a robots.txt product token
+ * only, with no user agent of its own, so a UA probe for it would compare the
+ * site against a string that never appears in real traffic.
+ */
+declare const AI_CRAWLER_UAS: ReadonlyArray<{
+    token: string;
+    ua: string;
+    label: string;
+}>;
+/** A mainstream browser UA. The control half of every pair. */
+declare const BASELINE_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36";
+/**
+ * How a site answered a crawler UA, relative to the same request as a browser.
+ *
+ * The classes are deliberately distinct rather than one "blocked" verdict:
+ * a Cloudflare interstitial, a pay-per-crawl price, a proof-of-work wall and a
+ * rate limit each need a different remedy from the operator, and an opaque 403
+ * may even be correct impersonation defence.
+ */
+type BlockClass = 'ok' | 'cf-challenge' | 'pay-per-crawl' | 'anubis-pow' | 'rate-limited' | 'opaque-403' | 'soft-block' | 'transport-error';
+interface UaProbe {
+    url: string;
+    token: string;
+    baselineStatus: number;
+    probeStatus: number;
+    blockClass: BlockClass;
+    /** Probe main-content length over baseline main-content length. */
+    textRatio: number;
+    /** The shortest decisive fact — a header line, a status, a body marker. */
+    evidence: string;
+    /** Main-content text of each side, kept so a caller can diff them word by word. */
+    baselineText: string;
+    probeText: string;
+    /** The raw baseline body, so a caller can resolve declared markup against the DOM a browser got. */
+    baselineBody: string;
+    /** The raw probe body, so a caller can look for challenge fingerprints the classifier does not model. */
+    probeBody: string;
+    /** Baseline response headers, so a caller can read a price or a payment challenge. */
+    baselineHeaders: Record<string, string>;
+    /** Probe response headers, for the same reason. */
+    probeHeaders: Record<string, string>;
+}
+/**
+ * Compare one crawler-UA response against the browser baseline for the same URL.
+ *
+ * A non-2xx baseline yields `ok` for every probe: the scanner could not read the
+ * page either, so nothing observed is bot-specific and reporting it would be a
+ * finding about our own fetch.
+ */
+declare function classifyResponse(baseline: FetchResult, probe: FetchResult): {
+    blockClass: BlockClass;
+    textRatio: number;
+    evidence: string;
+    baselineText: string;
+    probeText: string;
+    baselineBody: string;
+    probeBody: string;
+    baselineHeaders: Record<string, string>;
+    probeHeaders: Record<string, string>;
+};
+/**
+ * Fetch each URL once as a browser, then once per crawler token, and classify
+ * the difference.
+ *
+ * The baseline is fetched once per URL and reused across tokens, so a six-token
+ * sweep costs seven requests per URL rather than twelve. URLs are `isSafeUrl`-
+ * gated because callers pass in addresses read out of site-controlled content.
+ */
+declare function probeUaParity(fetch: (options: FetchOptions) => Promise<FetchResult>, urls: string[], tokens: string[], opts?: {
+    signal?: AbortSignal;
+}): Promise<UaProbe[]>;
+
+/** One `<url>` row of a sitemap. */
+interface SitemapEntry {
+    loc: string;
+    lastmod?: string;
+}
+/** The result of walking a site's advertised sitemap roots. */
+interface SitemapTree {
+    entries: SitemapEntry[];
+    /** Child sitemaps actually fetched, in order. Empty for a flat sitemap. */
+    childSitemaps: string[];
+    /** How many `<lastmod>` values failed the W3C Datetime shape. */
+    malformedLastmod: number;
+    /** True when a cap stopped the walk, so `entries` is not the whole tree. */
+    truncated: boolean;
+}
+/**
+ * Does this value parse as a W3C Datetime, the format the sitemap protocol
+ * requires of `<lastmod>`?
+ *
+ * Accepts the date-only `YYYY-MM-DD` form and the full RFC 3339 timestamp.
+ * Deliberately strict about the shape before handing anything to `Date`, which
+ * would happily accept `1755859200` (epoch seconds, a common CMS bug) and
+ * every prose string a locale parser recognises.
+ */
+declare function isW3CDateTime(value: string): boolean;
+/**
+ * Walk a site's sitemap roots and collect their `<url>` rows.
+ *
+ * Recursion stops after one level of `<sitemapindex>`: the depth of a nested
+ * index is chosen by the site being scanned, so following it arbitrarily is an
+ * unbounded walk driven by untrusted input. Every child URL is `isSafeUrl`- and
+ * same-host-gated before it is fetched, for the same reason.
+ */
+declare function collectSitemapEntries(fetch: (options: FetchOptions) => Promise<FetchResult>, roots: string[], opts?: {
+    maxChildren?: number;
+    maxEntries?: number;
+    signal?: AbortSignal;
+}): Promise<SitemapTree>;
+/**
+ * Take an even-strided sample of `n` entries.
+ *
+ * Deterministic rather than random: two audits sampling the same tree must
+ * probe the same URLs, or a finding from one cannot be lined up against a
+ * finding from the other.
+ */
+declare function sampleEntries(entries: SitemapEntry[], n: number): SitemapEntry[];
+
+/** One `selector { declarations }` rule, with the at-rule it sits inside. */
+interface CssRule {
+    /** The full selector list, verbatim, so a human can adjudicate a match. */
+    selector: string;
+    /** The declaration block, lowercased and whitespace-collapsed. */
+    declarations: string;
+    /** The enclosing at-rule prelude (`media print`, `supports (...)`), if any. */
+    atRule?: string;
+    /** Where the rule came from, for evidence. */
+    origin: 'inline' | string;
+}
+/**
+ * Scan a stylesheet into flat selector/declaration pairs.
+ *
+ * Deliberately a scanner, not a parser: it performs no cascade, no specificity
+ * ordering and no media-query evaluation. It exists so an audit can ask "does
+ * any rule that could apply to this element declare display:none", and it
+ * reports the matched selector text so a human can check the answer. A full CSS
+ * engine would need a dependency the core package does not carry.
+ */
+declare function parseCssRules(source: string, origin?: string): CssRule[];
+interface PageCss {
+    rules: CssRule[];
+    /** Stylesheet URLs on another origin, which are never fetched. */
+    skippedCrossOrigin: string[];
+    /** Stylesheet URLs fetched and scanned. */
+    fetched: string[];
+}
+/**
+ * Collect every CSS rule a page's own markup and same-origin stylesheets carry.
+ *
+ * Cross-origin sheets are not fetched: a scan must not pull bytes from a third
+ * party on the scanned site's behalf. They are reported instead, so a result
+ * built on partial CSS says so rather than reading as complete.
+ */
+declare function collectPageCss(ctx: CheckContext, page: PageContext): Promise<PageCss>;
+
+declare function pagesOfType(ctx: CheckContext, ...types: PageType[]): PageContext[];
+interface PageJudgement {
+    page: PageContext;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Run one judgement over a set of pages. v1 audits frequently judged only
+ * pages[0] and generalized to the whole site; this makes per-page judgement
+ * the path of least resistance. Callers MUST return notApplicable when
+ * `judged.length === 0` — an empty set proves nothing.
+ */
+declare function judgePages(pages: PageContext[], judge: (page: PageContext) => {
+    ok: boolean;
+    detail?: string;
+}): {
+    judged: PageJudgement[];
+    passRate: number;
+    failures: PageJudgement[];
+};
 
 declare function parseHtml(html: string): CheerioAPI;
 declare function extractJsonLd($: CheerioAPI): object[];
 /**
- * Flatten parsed JSON-LD into a flat list of schema.org nodes.
+ * Top-level JSON-LD entities only: expands arrays and `@graph` members,
+ * propagating `@context` downward. Nested property objects (an Article's
+ * `publisher`, a Product's `offers`) are NOT hoisted — v1's deep flatten
+ * made audits "find" entities the page never declared at top level.
+ */
+declare function topLevelJsonLd(blocks: object[]): object[];
+/**
+ * Every JSON-LD node including nested ones — for audits that legitimately
+ * search deep (e.g. AggregateRating nested under Product).
  *
  * Real-world JSON-LD nests the interesting types arbitrarily: a top-level
  * `[{...}]` array (common on Shopify), an `@graph` container, and properties
@@ -447,7 +993,9 @@ declare function extractJsonLd($: CheerioAPI): object[];
  * invisible — producing false "schema not found" verdicts. This walks every
  * object and array value so type/property lookups see the whole graph.
  */
-declare function flattenJsonLd(blocks: object[]): object[];
+declare function allJsonLdNodes(blocks: object[]): object[];
+/** @deprecated v1 name for the deep walk. Use topLevelJsonLd (structure) or allJsonLdNodes (deep search). Removed in v2. */
+declare const flattenJsonLd: typeof allJsonLdNodes;
 /**
  * Extract links from Markdown-ish text (llms.txt, READMEs).
  *
@@ -475,7 +1023,28 @@ declare function extractHeadings($: CheerioAPI): Array<{
     level: number;
     text: string;
 }>;
+/**
+ * The text of the page's main content region.
+ *
+ * Answers what the main content says, so page chrome — navigation, headers,
+ * footers, cookie banners — stays out of it. Among several <main> elements the
+ * one holding the most text wins: themes ship empty or fragmented <main>
+ * wrappers, and the first one is often a short stub. Falls back to the whole
+ * <body> only when no <main> holds any text.
+ *
+ * For shell detection — did the server render any readable text at all — use
+ * `getRenderedText` instead.
+ */
 declare function getMainContentText($: CheerioAPI): string;
+/**
+ * The text of the served HTML body, minus script/style/noscript/template.
+ *
+ * Answers whether the server rendered any readable text at all, so page chrome
+ * counts: a shell that ships only a nav and a footer is exactly what this has
+ * to see. Use `getMainContentText` when the question is what the main content
+ * says rather than whether anything was served.
+ */
+declare function getRenderedText($: CheerioAPI): string;
 declare function getWordCount($: CheerioAPI): number;
 declare function extractImages($: CheerioAPI): Array<{
     src: string;
@@ -486,6 +1055,9 @@ declare function extractImages($: CheerioAPI): Array<{
     loading?: string;
     role?: string;
     ariaHidden?: string;
+    ariaLabel?: string;
+    ariaLabelledby?: string;
+    title?: string;
 }>;
 declare function extractForms($: CheerioAPI): Array<{
     action: string;
@@ -525,7 +1097,9 @@ declare const MAX_CONCURRENT_REQUESTS = 10;
 declare const SCANNER_USER_AGENT = "AgentLighthouse/1.0 (+https://github.com/ForkPoint/agent-lighthouse)";
 declare const TAG_SKIPPED_PAGE_TYPE = "skipped:page-type";
 declare const TAG_SCAN_ERROR = "scan-error";
-declare const CATEGORY_WEIGHTS: Record<string, number>;
+/** An audit the scan could not feed: it needs evidence this scan never got. */
+declare const TAG_SKIPPED_NO_EVIDENCE = "skipped:no-evidence";
+/** Display names for the 8 v2 categories. */
 declare const CATEGORY_NAMES: Record<string, string>;
 declare const READINESS_WEIGHTS: {
     readonly commerce: 0.4;
@@ -538,6 +1112,12 @@ declare const SCORE_TIER_LABELS: Record<ScoreTier, string>;
 declare function getTierLabel(tier: string | null): string;
 declare function getTierColor(tier: string | null): string;
 
+/**
+ * Spec §4 weight law: an audit's scoring weight is a pure function of its
+ * evidence grade and tier. Only the `scored` tier carries weight, and only
+ * grades A and B are proven enough to move a score.
+ */
+declare function weightForGrade(grade: EvidenceGrade, tier: AuditTier): number;
 /**
  * Single source of truth for "this check is advisory only".
  *
@@ -548,7 +1128,15 @@ declare function getTierColor(tier: string | null): string;
  */
 declare function isInformative(check: Pick<CheckResult, 'scoreDisplayMode'>): boolean;
 declare function calculateCategoryScore(checks: CheckResult[]): number;
-declare function buildCategoryResult(id: string, checks: CheckResult[]): CategoryResult;
+/**
+ * Assemble a category result.
+ *
+ * `mass` is the category's evidence mass — the summed weight of its registered
+ * audits (`CATEGORY_MASS` in audit-config). It is passed in rather than looked
+ * up so this module stays free of a dependency on the registry, which the
+ * audits themselves import (for `weightForGrade`).
+ */
+declare function buildCategoryResult(id: string, checks: CheckResult[], mass?: number): CategoryResult;
 declare function calculateOverallScore(categories: CategoryResult[]): number;
 
 /**
@@ -572,17 +1160,19 @@ declare const AuditResultSchema: z.ZodObject<{
         expected: z.ZodOptional<z.ZodString>;
         found: z.ZodOptional<z.ZodString>;
         code: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-    }, {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-    }>>;
+    }, "strip", z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, z.objectOutputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip">, z.objectInputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip">>>;
     pageUrl: z.ZodUnion<[z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>, z.ZodString]>;
     priority: z.ZodOptional<z.ZodEnum<["critical", "high", "medium", "low"]>>;
+    /** A fix written from what this scan found, which beats the generic one in meta.guidance. */
+    remediation: z.ZodOptional<z.ZodString>;
     code: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     status: "warn" | "pass" | "fail" | "na";
@@ -590,32 +1180,34 @@ declare const AuditResultSchema: z.ZodObject<{
     code?: string | undefined;
     found?: string | undefined;
     expected?: string | undefined;
-    details?: {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-    } | undefined;
+    details?: z.objectOutputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip"> | undefined;
     message?: string | undefined;
     displayValue?: string | undefined;
     explanation?: string | undefined;
     pageUrl?: string | undefined;
     priority?: "critical" | "high" | "medium" | "low" | undefined;
+    remediation?: string | undefined;
 }, {
     status: "warn" | "pass" | "fail" | "na";
     score: number;
     code?: string | undefined;
     found?: string | undefined;
     expected?: string | undefined;
-    details?: {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-    } | undefined;
+    details?: z.objectInputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip"> | undefined;
     message?: string | undefined;
     displayValue?: string | undefined;
     explanation?: string | undefined;
     pageUrl?: string | undefined;
     priority?: "critical" | "high" | "medium" | "low" | undefined;
+    remediation?: string | undefined;
 }>;
 declare const FixEffortSchema: z.ZodEnum<["trivial", "easy", "moderate", "complex"]>;
 declare const AuditGuidanceSchema: z.ZodObject<{
@@ -651,6 +1243,13 @@ declare const DeprecationNoticeSchema: z.ZodObject<{
     link: string;
     notice: string;
 }>;
+/** Evidence strength from the audit's dossier (docs/evidence/policy.md). */
+declare const EvidenceGradeSchema: z.ZodEnum<["A", "B", "C", "D"]>;
+/** Scoring participation tier (spec §4). */
+declare const AuditTierSchema: z.ZodEnum<["scored", "informative", "experimental"]>;
+/** v2 audit identity: `category/slug`, stable across releases (spec §6). */
+declare const AUDIT_ID_PATTERN: RegExp;
+declare const EvidenceKeySchema: z.ZodEnum<["origin-reachable", "unblocked-fetches", "rendered-body", "sample-adequate"]>;
 declare const AuditMetaSchema: z.ZodObject<{
     id: z.ZodString;
     category: z.ZodString;
@@ -693,6 +1292,10 @@ declare const AuditMetaSchema: z.ZodObject<{
         link: string;
         notice: string;
     }>>;
+    evidenceGrade: z.ZodEnum<["A", "B", "C", "D"]>;
+    tier: z.ZodEnum<["scored", "informative", "experimental"]>;
+    dossier: z.ZodString;
+    requires: z.ZodOptional<z.ZodArray<z.ZodEnum<["origin-reachable", "unblocked-fetches", "rendered-body", "sample-adequate"]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     category: string;
     title: string;
@@ -702,6 +1305,9 @@ declare const AuditMetaSchema: z.ZodObject<{
     scoreDisplayMode: "binary" | "ternary" | "informative";
     weight: number;
     defaultPriority: "critical" | "high" | "medium" | "low";
+    evidenceGrade: "A" | "B" | "C" | "D";
+    tier: "informative" | "scored" | "experimental";
+    dossier: string;
     applicablePageTypes?: string[] | undefined;
     guidance?: {
         impact: string;
@@ -715,6 +1321,7 @@ declare const AuditMetaSchema: z.ZodObject<{
         link: string;
         notice: string;
     } | undefined;
+    requires?: ("origin-reachable" | "unblocked-fetches" | "rendered-body" | "sample-adequate")[] | undefined;
 }, {
     category: string;
     title: string;
@@ -724,6 +1331,9 @@ declare const AuditMetaSchema: z.ZodObject<{
     scoreDisplayMode: "binary" | "ternary" | "informative";
     weight: number;
     defaultPriority: "critical" | "high" | "medium" | "low";
+    evidenceGrade: "A" | "B" | "C" | "D";
+    tier: "informative" | "scored" | "experimental";
+    dossier: string;
     applicablePageTypes?: string[] | undefined;
     guidance?: {
         impact: string;
@@ -737,6 +1347,7 @@ declare const AuditMetaSchema: z.ZodObject<{
         link: string;
         notice: string;
     } | undefined;
+    requires?: ("origin-reachable" | "unblocked-fetches" | "rendered-body" | "sample-adequate")[] | undefined;
 }>;
 declare const CheckResultSchema: z.ZodObject<{
     id: z.ZodString;
@@ -757,17 +1368,20 @@ declare const CheckResultSchema: z.ZodObject<{
         found: z.ZodOptional<z.ZodString>;
         code: z.ZodOptional<z.ZodString>;
         docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
-    }, "strip", z.ZodTypeAny, {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-        docsUrl?: string | undefined;
-    }, {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-        docsUrl?: string | undefined;
-    }>>;
+        evidenceUrl: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, z.objectOutputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
+        evidenceUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip">, z.objectInputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
+        evidenceUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip">>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     deprecated: z.ZodOptional<z.ZodObject<{
         notice: z.ZodString;
@@ -779,6 +1393,8 @@ declare const CheckResultSchema: z.ZodObject<{
         link: string;
         notice: string;
     }>>;
+    evidenceGrade: z.ZodOptional<z.ZodEnum<["A", "B", "C", "D"]>>;
+    tier: z.ZodOptional<z.ZodEnum<["scored", "informative", "experimental"]>>;
 }, "strip", z.ZodTypeAny, {
     status: "warn" | "pass" | "fail" | "na";
     category: string;
@@ -790,12 +1406,13 @@ declare const CheckResultSchema: z.ZodObject<{
     fix: string;
     description: string;
     scoreDisplayMode: "binary" | "ternary" | "informative";
-    details?: {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-        docsUrl?: string | undefined;
-    } | undefined;
+    details?: z.objectOutputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
+        evidenceUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip"> | undefined;
     displayValue?: string | undefined;
     explanation?: string | undefined;
     pageUrl?: string | undefined;
@@ -804,6 +1421,8 @@ declare const CheckResultSchema: z.ZodObject<{
         link: string;
         notice: string;
     } | undefined;
+    evidenceGrade?: "A" | "B" | "C" | "D" | undefined;
+    tier?: "informative" | "scored" | "experimental" | undefined;
 }, {
     status: "warn" | "pass" | "fail" | "na";
     category: string;
@@ -815,12 +1434,13 @@ declare const CheckResultSchema: z.ZodObject<{
     fix: string;
     description: string;
     scoreDisplayMode: "binary" | "ternary" | "informative";
-    details?: {
-        code?: string | undefined;
-        found?: string | undefined;
-        expected?: string | undefined;
-        docsUrl?: string | undefined;
-    } | undefined;
+    details?: z.objectInputType<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
+        evidenceUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>, "strip"> | undefined;
     displayValue?: string | undefined;
     explanation?: string | undefined;
     pageUrl?: string | undefined;
@@ -829,6 +1449,8 @@ declare const CheckResultSchema: z.ZodObject<{
         link: string;
         notice: string;
     } | undefined;
+    evidenceGrade?: "A" | "B" | "C" | "D" | undefined;
+    tier?: "informative" | "scored" | "experimental" | undefined;
 }>;
 
 declare function normalizeUrl(input: string): string;
@@ -883,4 +1505,15 @@ declare class Logger {
 }
 declare const logger: Logger;
 
-export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditPlan, type AuditProgressEvent, type AuditRegistration, type AuditResult, AuditResultSchema, type AuditRunResult, CATEGORY_NAMES, CATEGORY_WEIGHTS, type CategoryConfig, type CategoryResult, type CheckContext, type CheckFn, type CheckPriority, CheckPrioritySchema, type CheckRecommendation, type CheckResult, CheckResultSchema, type CheckStatus, CheckStatusSchema, DEFAULT_SCAN_LIMIT, type DeprecationNotice, DeprecationNoticeSchema, type FetchOptions, type FetchResult, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, PAGE_TYPE_LABELS, PHASE_WEIGHTS, PRESETS, type PageContext, type PageOverride, type PageType, type PhaseId, type PresetName, type PresetOptions, type ProductFieldVerification, ProgressTracker, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanEvent, type ScanOptions, type ScanReport, type ScoreDisplayMode, ScoreDisplayModeSchema, type ScoreTier, TAG_SCAN_ERROR, TAG_SKIPPED_PAGE_TYPE, type WafProtection, buildCategoryResult, calculateCategoryScore, calculateOverallScore, createFetcher, defaultConfig, defineConfig, detectPageType, detectWafProtection, extractDomain, extractForms, extractHeadLinks, extractHeadings, extractImages, extractInternalLinks, extractJsonLd, extractMarkdownLinks, extractMetaTags, extractNavLinks, extractProductFieldVerification, extractScripts, extractStylesheetUrls, flattenJsonLd, getMainContentText, getPreset, getScoreTier, getTierColor, getTierLabel, getWordCount, isInformative, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, planAudits, runAudits, runScan };
+/** The ACP CheckoutSession `links` enum, in spec order. */
+declare const ACP_LINK_TYPES: readonly ["terms_of_use", "privacy_policy", "return_policy", "shipping_policy", "contact_us", "about_us", "faq", "support"];
+type AcpLinkType = (typeof ACP_LINK_TYPES)[number];
+/**
+ * The first same-page candidate URL for each ACP link type, in document order.
+ *
+ * Classification is by URL path first, anchor text second, so a link whose path
+ * is opaque (`/p/12345`) is still classified when its label is not.
+ */
+declare function resolvePolicyLinks(ctx: CheckContext): Map<AcpLinkType, string>;
+
+export { ACP_LINK_TYPES, AI_CRAWLER_UAS, AUDIT_ID_PATTERN, type AcpLinkType, type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditPlan, type AuditProgressEvent, type AuditRegistration, type AuditResult, AuditResultSchema, type AuditRunResult, type AuditTier, AuditTierSchema, type AuditTrace, type AuditTraceHandler, BASELINE_UA, type BlockClass, CATEGORY_IDS, CATEGORY_MASS, CATEGORY_NAMES, type CategoryConfig, type CategoryResult, type CheckContext, type CheckFn, type CheckPriority, CheckPrioritySchema, type CheckRecommendation, type CheckResult, CheckResultSchema, type CheckStatus, CheckStatusSchema, type CssRule, DEFAULT_SCAN_LIMIT, type DeprecationNotice, DeprecationNoticeSchema, type EvidenceGrade, EvidenceGradeSchema, type EvidenceKey, EvidenceKeySchema, type ExpectedKind, type FetchClass, type FetchOptions, type FetchResult, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, PAGE_TYPE_LABELS, PHASE_WEIGHTS, PRESETS, type PageContext, type PageCss, type PageJudgement, type PageOverride, type PageType, type PhaseId, type PresetName, type PresetOptions, type ProductFieldVerification, ProgressTracker, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, type RobotsFile, type RobotsGroup, type RobotsRule, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanEvent, type ScanEvidence, type ScanOptions, type ScanReport, type ScanValidity, type ScoreDisplayMode, ScoreDisplayModeSchema, type ScoreTier, type SitemapEntry, type SitemapTree, TAG_SCAN_ERROR, TAG_SKIPPED_NO_EVIDENCE, TAG_SKIPPED_PAGE_TYPE, type UaProbe, type WafProtection, allEvidenceMet, allJsonLdNodes, buildCategoryResult, buildScanEvidence, calculateCategoryScore, calculateOverallScore, classifyFetch, classifyResponse, collectPageCss, collectSitemapEntries, createFetcher, defaultConfig, defineConfig, detectPageType, detectWafProtection, evidenceUrl, extractDomain, extractForms, extractHeadLinks, extractHeadings, extractImages, extractInternalLinks, extractJsonLd, extractMarkdownLinks, extractMetaTags, extractNavLinks, extractProductFieldVerification, extractScripts, extractStylesheetUrls, filterConfig, flattenJsonLd, formatTrace, getMainContentText, getPreset, getRenderedText, getScoreTier, getTierColor, getTierLabel, getWordCount, groupsForBot, hasNamedGroup, isBlanketBlocked, isInformative, isPathAllowed, isPrivateIp, isRealFile, isSafeUrl, isW3CDateTime, joinUrl, judgePages, loadConfigFile, logger, matchesUserAgent, normalizeNewlines, normalizeUrl, outcomeOf, pagesOfType, parseCssRules, parseHtml, parseRobots, parseRobotsFile, planAudits, probeUaParity, resolvePolicyLinks, runAudits, runScan, sampleEntries, stripBom, topLevelJsonLd, traceFromCheck, weightForGrade };