@forkpoint/agent-lighthouse-core 3.0.0 → 4.0.0

package/dist/index.d.mts

@@ -1,12 +1,14 @@
+import { Dispatcher } from 'undici';
 import { CheerioAPI } from 'cheerio';
 import { z } from 'zod';
 
+declare function isSafeUrl(url: string): Promise<boolean>;
 interface FetchOptions {
     url: string;
     timeout?: number;
     followRedirects?: boolean;
     acceptHeader?: string;
-    method?: 'GET' | 'POST' | 'OPTIONS' | 'HEAD' | 'DELETE';
+    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). */
@@ -56,18 +58,54 @@ interface FetchResult {
     }>;
     error?: string;
 }
+interface FetcherOptions {
+    /**
+     * undici dispatcher for every request this fetcher makes.
+     *
+     * Omitted, requests go through a shared `new Agent()` whose per-origin
+     * connection count is unlimited — right for a site owner scanning their own
+     * site, who wants the scan over quickly. A caller scanning origins that did
+     * not invite it passes a bounded agent (`new Agent({ connections: 2 })`) so
+     * one scan cannot open 28 sockets at once against a stranger's WAF.
+     */
+    dispatcher?: Dispatcher;
+    /**
+     * How many requests this fetcher may have in flight at once.
+     *
+     * Omitted, there is no ceiling and every request is issued as it arrives.
+     *
+     * A bounded dispatcher alone is not enough for a caller that wants one, and
+     * the difference is what the clocks measure. `Agent({ connections: 2 })`
+     * accepts all 26 root-file requests the scan fires in one `Promise.all` and
+     * queues 24 of them inside undici — but the per-request deadline and the
+     * `ttfbMs` clock both start when `fetch()` is called, so an origin averaging
+     * 800 ms per file would have its tail requests time out on the scanner's own
+     * queue and be reported as unreachable. Waiting here instead holds a request
+     * outside both clocks until it can actually be issued, so what they measure
+     * is the origin.
+     */
+    maxConcurrent?: number;
+    /**
+     * Extra HTTP headers sent with every request from this fetcher.
+     */
+    headers?: Record<string, string>;
+}
 /**
- * Validates that a URL is safe to fetch (http/https scheme, non-private IP).
- * Use before fetching any URL extracted from scanned site content.
+ * A dispatcher that opens at most `connections` sockets per origin.
+ *
+ * The scanner's own default has no such ceiling, and for a site owner scanning
+ * their own site that is the right trade. A caller scanning origins that did
+ * not invite it wants the ceiling, and this saves it from taking a direct
+ * dependency on undici to express one line of politeness.
  */
-declare function isSafeUrl(url: string): Promise<boolean>;
-declare function createFetcher(): {
+declare function boundedDispatcher(connections: number): Dispatcher;
+declare function createFetcher(fetcherOptions?: FetcherOptions): {
     fetch: (options: FetchOptions) => Promise<FetchResult>;
 };
 
 interface WafProtection {
     isBlocked: boolean;
-    provider?: 'akamai' | 'cloudflare' | 'datadome' | 'perimeterx' | 'imperva' | 'kasada' | 'aws-waf' | 'generic-waf' | 'connection-drop' | 'rate-limited';
+    provider?: "akamai" | "cloudflare" | "datadome" | "perimeterx" | "imperva" | "kasada" | "aws-waf" | "generic-waf" | "connection-drop" | "rate-limited";
     name: string;
     reason: string;
     statusCode?: number;
@@ -89,7 +127,7 @@ interface WafProtection {
  */
 declare function detectWafProtection(targetUrl: string, homepageResult: FetchResult | null, rootFiles: Record<string, FetchResult>, scannedPagesCount: number): WafProtection | null;
 
-type PageType = 'homepage' | 'category' | 'product' | 'content';
+type PageType = "homepage" | "category" | "product" | "content";
 declare const PAGE_TYPE_LABELS: Record<PageType, string>;
 /**
  * A user-supplied page to scan with an explicit type.
@@ -99,7 +137,7 @@ interface PageOverride {
     pageType: PageType;
 }
 /** Per-field presence in a product page's structured data. */
-type FieldStatus = 'found' | 'partial' | 'missing';
+type FieldStatus = "found" | "partial" | "missing";
 /**
  * Field-level verification of a product page, read directly from its structured
  * data (JSON-LD + Microdata + RDFa).
@@ -115,7 +153,7 @@ interface ProductFieldVerification {
     reviewCount: FieldStatus;
     sourceUrl?: string;
 }
-type FixEffort = 'trivial' | 'easy' | 'moderate' | 'complex';
+type FixEffort = "trivial" | "easy" | "moderate" | "complex";
 interface AuditGuidance {
     /** Customer-facing explanation of business impact when this audit fails */
     impact: string;
@@ -130,7 +168,7 @@ interface AuditGuidance {
     /** Tags for filtering/grouping in the report UI */
     tags?: string[];
 }
-type ScoreDisplayMode = 'binary' | 'ternary' | 'informative';
+type ScoreDisplayMode = "binary" | "ternary" | "informative";
 /** 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. */
@@ -142,12 +180,12 @@ interface DeprecationNotice {
  * 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';
+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';
+type AuditTier = "scored" | "informative" | "experimental";
 interface AuditMeta {
     id: string;
     category: string;
@@ -156,6 +194,7 @@ interface AuditMeta {
     description: string;
     scoreDisplayMode: ScoreDisplayMode;
     weight: number;
+    pageTypes?: PageType[];
     applicablePageTypes?: PageType[];
     defaultPriority: CheckPriority;
     guidance?: AuditGuidance;
@@ -185,7 +224,7 @@ interface AuditMeta {
  * 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';
+type EvidenceKey = "origin-reachable" | "unblocked-fetches" | "rendered-body" | "sample-adequate";
 interface AuditResult {
     status: CheckStatus;
     score: number;
@@ -210,8 +249,8 @@ interface AuditResult {
      */
     remediation?: string;
 }
-type CheckStatus = 'pass' | 'warn' | 'fail' | 'na';
-type CheckPriority = 'critical' | 'high' | 'medium' | 'low';
+type CheckStatus = "pass" | "warn" | "fail" | "na";
+type CheckPriority = "critical" | "high" | "medium" | "low";
 interface CheckRecommendation {
     priority: CheckPriority;
     description: string;
@@ -260,8 +299,10 @@ interface CategoryResult {
     passCount: number;
     warnCount: number;
     failCount: number;
+    registryMass?: number;
+    assessedMass?: number;
 }
-type ScoreTier = 'agent-ready' | 'partially-ready' | 'needs-work' | 'not-ready';
+type ScoreTier = "agent-ready" | "partially-ready" | "needs-work" | "not-ready";
 /**
  * Whether a verdict about this site can mean anything, and what is missing.
  *
@@ -311,6 +352,39 @@ interface ScanReport {
     readinessVitals?: ReadinessVitals;
     productFields?: ProductFieldVerification;
     wafProtection?: WafProtection;
+    originEvidence?: {
+        origin: string;
+        version: string;
+        readAt: string;
+        cached: boolean;
+    };
+    conditions?: ScanConditions;
+}
+interface ScanConditions {
+    url: string;
+    pageType: {
+        type: PageType;
+        source: "declared" | "detected";
+    };
+    origin: {
+        origin: string;
+        version: string;
+        readAt: string;
+        cached: boolean;
+    };
+    coverage: {
+        registryMass: number;
+        assessedMass: number;
+        pageMass: number;
+        originMass: number;
+        gatedMass: number;
+    };
+    unscored: {
+        totalCount: number;
+        informativeCount: number;
+        gatedCount: number;
+        reasons: Record<string, number>;
+    };
 }
 interface ReadinessVitals {
     commerce: number;
@@ -319,6 +393,54 @@ interface ReadinessVitals {
     technical: number;
 }
 
+interface OriginCacheOptions {
+    bypassOriginCache?: boolean;
+    headers?: Record<string, string>;
+}
+interface OriginEvidence {
+    origin: string;
+    version: string;
+    readAt: string;
+    rootFiles: Record<string, FetchResult>;
+    originHomepage?: FetchResult;
+}
+/**
+ * Derives a canonical anonymous origin cache key.
+ *
+ * Strips any userinfo/credentials from the URL so credentials never leak into
+ * cache keys. Request headers other than credentials are folded in as a
+ * fingerprint: a scan that sets a bot user agent must not share a slot with
+ * a default scan, since the origin may answer the two differently.
+ */
+declare function computeOriginCacheKey(url: string, version?: string, headers?: Record<string, string>): string;
+/**
+ * Determines whether the scan must bypass the shared origin cache.
+ * Authenticated scans (URL credentials, Authorization header, cookies) or explicit bypass flags bypass the shared cache.
+ */
+declare function shouldBypassOriginCache(url: string, options?: OriginCacheOptions): boolean;
+/**
+ * A bounded, TTL-evicting store of origin evidence.
+ *
+ * Expired entries are swept on every write, and the oldest entry is dropped
+ * when the store is full, so a process that scans many origins once each
+ * cannot grow without limit. A read of an expired key evicts it as well.
+ */
+declare class OriginCache {
+    private cache;
+    private ttlMs;
+    private maxEntries;
+    constructor(ttlMs?: number, maxEntries?: number);
+    /** Drop every entry whose TTL has passed. */
+    sweep(now?: number): void;
+    get(key: string): OriginEvidence | undefined;
+    has(key: string): boolean;
+    set(key: string, evidence: OriginEvidence, ttlMs?: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+declare const defaultOriginCache: OriginCache;
+
 /**
  * What a scan actually obtained, decided once, before any audit runs.
  *
@@ -356,7 +478,7 @@ interface A11yNodeFinding {
     target: string;
     summary: string;
 }
-type A11yStatus = 'pass' | 'fail' | 'incomplete' | 'inapplicable';
+type A11yStatus = "pass" | "fail" | "incomplete" | "inapplicable";
 interface A11yRuleResult {
     status: A11yStatus;
     nodes: A11yNodeFinding[];
@@ -367,6 +489,7 @@ type A11yPageResult = Record<string, A11yRuleResult>;
 interface PageContext {
     url: string;
     pageType: PageType;
+    pageTypeSource?: "declared" | "detected";
     fetchResult: FetchResult;
     $: CheerioAPI;
     /** Parsed JSON-LD blocks only (used by JSON-LD-specific audits). */
@@ -399,6 +522,15 @@ interface CheckContext {
     baseUrl: string;
     fetch: (options: FetchOptions) => Promise<FetchResult>;
     wafProtection?: WafProtection;
+    /**
+     * The object per-scan gatherer caches key on.
+     *
+     * The runner hands each audit a scoped copy of this context, and a copy has
+     * a new identity. Without this stamp every gatherer `WeakMap` would miss
+     * once per audit and repeat its fetch. The runner sets it on each copy;
+     * an unstamped context is its own owner. See `gatherers/cache-owner.ts`.
+     */
+    cacheOwner?: object;
     /**
      * What the scan actually obtained, decided once before any audit ran.
      *
@@ -407,6 +539,16 @@ interface CheckContext {
      * harnesses that do not exercise the gate pass `allEvidenceMet()`.
      */
     evidence: ScanEvidence;
+    /**
+     * Origin evidence metadata and cached homepage response.
+     */
+    originEvidence?: {
+        origin: string;
+        version: string;
+        readAt: string;
+        cached: boolean;
+        originHomepage?: FetchResult;
+    };
 }
 type CheckFn = (ctx: CheckContext) => CheckResult | Promise<CheckResult>;
 
@@ -460,7 +602,7 @@ declare abstract class Audit {
         [key: string]: unknown;
     } | string, pageUrl?: string): AuditResult;
     /** Merge static meta with the runtime result to produce a CheckResult. */
-    toCheckResult(rawResult: AuditResult): CheckResult;
+    toCheckResult(rawResult: AuditResult, overrideDisplayMode?: ScoreDisplayMode): CheckResult;
 }
 
 interface CategoryConfig {
@@ -535,7 +677,7 @@ interface AuditTrace {
      * `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';
+    outcome: "ran" | "skipped" | "gated" | "error";
     status: CheckStatus;
     score: number;
     weight: number;
@@ -547,10 +689,10 @@ interface AuditTrace {
     explanation?: string;
     pageUrl?: string;
     /** The structured evidence behind the verdict, as the report carries it. */
-    details?: CheckResult['details'];
+    details?: CheckResult["details"];
 }
 /** Which outcome a finished check represents. */
-declare function outcomeOf(check: CheckResult): AuditTrace['outcome'];
+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. */
@@ -566,10 +708,10 @@ interface AuditRunResult {
  * ProgressTracker, which owns counting and fraction/elapsed stamping.
  */
 type AuditProgressEvent = {
-    type: 'unit:done';
+    type: "unit:done";
     label: string;
 } | {
-    type: 'unit:fail';
+    type: "unit:fail";
     label: string;
     error: string;
 };
@@ -582,29 +724,37 @@ type AuditProgressEvent = {
  */
 type AuditTraceHandler = (trace: AuditTrace) => void;
 interface AuditPlan {
-    runnable: Array<{
-        reg: AuditRegistration;
-        categoryId: string;
-    }>;
+    runnable: RunnableAudit[];
     skipped: CheckResult[];
 }
 /** How `planAudits` should treat audits the scan cannot feed. */
 interface PlanOptions {
     /**
-     * Skip audits whose `requires` the scan did not obtain.
+     * Skip audits whose `requires` the scan did not obtain. **Defaults to true.**
      *
-     * 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.
+     * An audit's `requires` decides what a blocked or client-rendered scan
+     * reports, so a caller that omits this option gets the gated set — the same
+     * set a scan gets. A production diagnostic may pass `false` to bypass only
+     * these per-audit `requires` checks. It is never the default, and it never
+     * bypasses the unconditional unread-scan guard.
      */
     enforceEvidence?: boolean;
 }
+interface RunnableAudit {
+    reg: AuditRegistration;
+    categoryId: string;
+    scopedPages?: PageContext[];
+    scoreDisplayMode?: ScoreDisplayMode;
+}
 /**
  * Split a scan config into the audits that will actually execute and 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, options?: PlanOptions): AuditPlan;
+declare function planAudits(ctx: CheckContext, config: ScanConfig, options?: PlanOptions): {
+    runnable: RunnableAudit[];
+    skipped: CheckResult[];
+};
 /**
  * Execute all audits registered in the config against the scan context.
  * Returns check results grouped into categories with weighted scores.
@@ -612,20 +762,20 @@ declare function planAudits(ctx: CheckContext, config: ScanConfig, options?: Pla
  */
 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 PhaseId = "fetch-root" | "fetch-pages" | "analyze" | "audits" | "report";
 type ScanEvent = {
-    type: 'scan:start';
+    type: "scan:start";
     url: string;
     fraction: number;
     elapsedMs: number;
 } | {
-    type: 'phase:start';
+    type: "phase:start";
     phase: PhaseId;
     totalUnits: number;
     fraction: number;
     elapsedMs: number;
 } | {
-    type: 'unit:done';
+    type: "unit:done";
     phase: PhaseId;
     completed: number;
     total: number;
@@ -633,20 +783,20 @@ type ScanEvent = {
     fraction: number;
     elapsedMs: number;
 } | {
-    type: 'unit:fail';
+    type: "unit:fail";
     phase: PhaseId;
     label: string;
     error: string;
     fraction: number;
     elapsedMs: number;
 } | {
-    type: 'phase:done';
+    type: "phase:done";
     phase: PhaseId;
     durationMs: number;
     fraction: number;
     elapsedMs: number;
 } | {
-    type: 'scan:done';
+    type: "scan:done";
     durationMs: number;
     /** Null when the scan obtained too little evidence to judge the site. */
     score: number | null;
@@ -693,6 +843,8 @@ declare class ProgressTracker {
 interface ScanOptions {
     onEvent?: (event: ScanEvent) => void;
     pages?: PageOverride[] | null;
+    /** Explicitly declared page type for the target URL. */
+    pageType?: PageType;
     signal?: AbortSignal;
     /**
      * Restrict the scan to these category ids. Unknown ids simply match nothing —
@@ -716,15 +868,41 @@ interface ScanOptions {
      *
      * 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.
+     * is never constructed. Set it to `false` to bypass only the per-audit
+     * `requires` checks. The unread-scan guard remains unconditional, so a scan
+     * that read no attributable site response still runs no audit.
      */
     enforceEvidenceGate?: boolean;
+    /**
+     * undici dispatcher for every request this scan makes.
+     */
+    dispatcher?: Dispatcher;
+    /**
+     * How many requests this scan may have in flight at once.
+     */
+    maxConcurrent?: number;
+    /**
+     * Extra HTTP request headers to pass on all fetches.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Explicitly bypass the shared origin evidence cache for this scan.
+     */
+    bypassOriginCache?: boolean;
+    /**
+     * Optional custom OriginCache instance (defaults to defaultOriginCache).
+     */
+    originCache?: OriginCache;
+    /**
+     * A `robots.txt` response the caller already has, used instead of fetching
+     * it again.
+     */
+    robotsTxt?: FetchResult;
 }
 declare function runScan(url: string, options?: ScanOptions): Promise<ScanReport>;
 
-type FetchClass = 'ok' | 'soft-404' | 'blocked' | 'missing' | 'error';
-type ExpectedKind = 'text' | 'json' | 'xml' | 'html';
+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;
 /**
@@ -740,7 +918,7 @@ declare function classifyFetch(result: FetchResult | undefined, expected: Expect
 declare function isRealFile(result: FetchResult | undefined, expected: ExpectedKind): boolean;
 
 interface RobotsRule {
-    type: 'allow' | 'disallow';
+    type: "allow" | "disallow";
     path: string;
 }
 interface RobotsGroup {
@@ -814,7 +992,7 @@ declare const BASELINE_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) App
  * 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';
+type BlockClass = "ok" | "cf-challenge" | "pay-per-crawl" | "anubis-pow" | "rate-limited" | "opaque-403" | "soft-block" | "transport-error";
 interface UaProbe {
     url: string;
     token: string;
@@ -881,6 +1059,10 @@ interface SitemapTree {
     malformedLastmod: number;
     /** True when a cap stopped the walk, so `entries` is not the whole tree. */
     truncated: boolean;
+    /** Sitemap files that answered 200 and parsed as a urlset or sitemapindex. */
+    readableFiles: string[];
+    /** Sitemap files that answered 200 but were neither. A soft-404 lands here. */
+    malformedFiles: string[];
 }
 /**
  * Does this value parse as a W3C Datetime, the format the sitemap protocol
@@ -895,6 +1077,11 @@ declare function isW3CDateTime(value: string): boolean;
 /**
  * Walk a site's sitemap roots and collect their `<url>` rows.
  *
+ * Every root in `roots` is read: a robots.txt that declares three sitemaps
+ * has three, and stopping at the first would judge a third of the site as
+ * the whole. `fallbackRoots` are the conventional paths, probed in order only
+ * when no declared root parsed, and the first one that does ends the probe.
+ *
  * 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
@@ -904,6 +1091,7 @@ declare function collectSitemapEntries(fetch: (options: FetchOptions) => Promise
     maxChildren?: number;
     maxEntries?: number;
     signal?: AbortSignal;
+    fallbackRoots?: string[];
 }): Promise<SitemapTree>;
 /**
  * Take an even-strided sample of `n` entries.
@@ -923,7 +1111,7 @@ interface CssRule {
     /** The enclosing at-rule prelude (`media print`, `supports (...)`), if any. */
     atRule?: string;
     /** Where the rule came from, for evidence. */
-    origin: 'inline' | string;
+    origin: "inline" | string;
 }
 /**
  * Scan a stylesheet into flat selector/declaration pairs.
@@ -1088,11 +1276,20 @@ declare function extractStylesheetUrls($: CheerioAPI): string[];
  */
 declare function detectPageType(url: string, $: CheerioAPI, jsonLd: object[], meta: Record<string, string>, isFirstPage: boolean): PageType;
 
-declare const DEFAULT_SCAN_LIMIT = 5;
-declare const MAX_PAGES_PER_SCAN = 6;
+declare const DEFAULT_SCAN_LIMIT = 1;
+declare const MAX_PAGES_PER_SCAN = 1;
+declare const ORIGIN_EVIDENCE_VERSION = "v1";
+declare const DEFAULT_ORIGIN_CACHE_TTL_MS: number;
+/**
+ * How many origins the shared cache holds at once. Each entry carries every
+ * root file of one origin, so a long-lived process (the MCP server, a looped
+ * live run) needs a ceiling, not only a TTL.
+ */
+declare const DEFAULT_ORIGIN_CACHE_MAX_ENTRIES = 256;
 declare const REQUEST_TIMEOUT_MS = 10000;
 declare const SCAN_TIMEOUT_MS = 60000;
 declare const MAX_RESPONSE_BODY_BYTES: number;
+/** @deprecated Unused internally; retained for published API stability. Scheduled for removal in v4. */
 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";
@@ -1126,7 +1323,7 @@ declare function weightForGrade(grade: EvidenceGrade, tier: AuditTier): number;
  * fails/passes or readiness vitals. Every surface that ranks or scores checks
  * filters through this predicate so the rule cannot drift per package.
  */
-declare function isInformative(check: Pick<CheckResult, 'scoreDisplayMode'>): boolean;
+declare function isInformative(check: Pick<CheckResult, "scoreDisplayMode">): boolean;
 declare function calculateCategoryScore(checks: CheckResult[]): number;
 /**
  * Assemble a category result.
@@ -1258,6 +1455,7 @@ declare const AuditMetaSchema: z.ZodObject<{
     description: z.ZodString;
     scoreDisplayMode: z.ZodEnum<["binary", "ternary", "informative"]>;
     weight: z.ZodNumber;
+    pageTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     applicablePageTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     defaultPriority: z.ZodEnum<["critical", "high", "medium", "low"]>;
     guidance: z.ZodOptional<z.ZodObject<{
@@ -1308,6 +1506,7 @@ declare const AuditMetaSchema: z.ZodObject<{
     evidenceGrade: "A" | "B" | "C" | "D";
     tier: "informative" | "scored" | "experimental";
     dossier: string;
+    pageTypes?: string[] | undefined;
     applicablePageTypes?: string[] | undefined;
     guidance?: {
         impact: string;
@@ -1334,6 +1533,7 @@ declare const AuditMetaSchema: z.ZodObject<{
     evidenceGrade: "A" | "B" | "C" | "D";
     tier: "informative" | "scored" | "experimental";
     dossier: string;
+    pageTypes?: string[] | undefined;
     applicablePageTypes?: string[] | undefined;
     guidance?: {
         impact: string;
@@ -1452,13 +1652,128 @@ declare const CheckResultSchema: z.ZodObject<{
     evidenceGrade?: "A" | "B" | "C" | "D" | undefined;
     tier?: "informative" | "scored" | "experimental" | undefined;
 }>;
+declare const PageTypeSchema: z.ZodEnum<["homepage", "category", "product", "content"]>;
+declare const ScanConditionsSchema: z.ZodObject<{
+    url: z.ZodString;
+    pageType: z.ZodObject<{
+        type: z.ZodEnum<["homepage", "category", "product", "content"]>;
+        source: z.ZodEnum<["declared", "detected"]>;
+    }, "strip", z.ZodTypeAny, {
+        type: "homepage" | "category" | "product" | "content";
+        source: "declared" | "detected";
+    }, {
+        type: "homepage" | "category" | "product" | "content";
+        source: "declared" | "detected";
+    }>;
+    origin: z.ZodObject<{
+        origin: z.ZodString;
+        version: z.ZodString;
+        readAt: z.ZodString;
+        cached: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        origin: string;
+        version: string;
+        readAt: string;
+        cached: boolean;
+    }, {
+        origin: string;
+        version: string;
+        readAt: string;
+        cached: boolean;
+    }>;
+    coverage: z.ZodObject<{
+        registryMass: z.ZodNumber;
+        assessedMass: z.ZodNumber;
+        pageMass: z.ZodNumber;
+        originMass: z.ZodNumber;
+        gatedMass: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        registryMass: number;
+        assessedMass: number;
+        pageMass: number;
+        originMass: number;
+        gatedMass: number;
+    }, {
+        registryMass: number;
+        assessedMass: number;
+        pageMass: number;
+        originMass: number;
+        gatedMass: number;
+    }>;
+    unscored: z.ZodObject<{
+        totalCount: z.ZodNumber;
+        informativeCount: z.ZodNumber;
+        gatedCount: z.ZodNumber;
+        reasons: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        reasons: Record<string, number>;
+        totalCount: number;
+        informativeCount: number;
+        gatedCount: number;
+    }, {
+        reasons: Record<string, number>;
+        totalCount: number;
+        informativeCount: number;
+        gatedCount: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    origin: {
+        origin: string;
+        version: string;
+        readAt: string;
+        cached: boolean;
+    };
+    pageType: {
+        type: "homepage" | "category" | "product" | "content";
+        source: "declared" | "detected";
+    };
+    coverage: {
+        registryMass: number;
+        assessedMass: number;
+        pageMass: number;
+        originMass: number;
+        gatedMass: number;
+    };
+    unscored: {
+        reasons: Record<string, number>;
+        totalCount: number;
+        informativeCount: number;
+        gatedCount: number;
+    };
+}, {
+    url: string;
+    origin: {
+        origin: string;
+        version: string;
+        readAt: string;
+        cached: boolean;
+    };
+    pageType: {
+        type: "homepage" | "category" | "product" | "content";
+        source: "declared" | "detected";
+    };
+    coverage: {
+        registryMass: number;
+        assessedMass: number;
+        pageMass: number;
+        originMass: number;
+        gatedMass: number;
+    };
+    unscored: {
+        reasons: Record<string, number>;
+        totalCount: number;
+        informativeCount: number;
+        gatedCount: number;
+    };
+}>;
 
 declare function normalizeUrl(input: string): string;
 declare function joinUrl(base: string, path: string): string;
 declare function extractDomain(url: string): string;
 declare function isPrivateIp(ip: string): boolean;
 
-type PresetName = 'ecommerce' | 'saas' | 'content' | 'quick' | 'full';
+type PresetName = "ecommerce" | "saas" | "content" | "quick" | "full";
 interface PresetOptions {
     name: PresetName;
     description: string;
@@ -1481,7 +1796,7 @@ interface AgentLighthouseConfig {
     /** Per-category minimum score assertions */
     assertCategories?: Record<string, number>;
     /** Output report formats (terminal, html, json, md) */
-    output?: Array<'terminal' | 'html' | 'json' | 'md'>;
+    output?: Array<"terminal" | "html" | "json" | "md">;
     /** Output directory for reports */
     outputDir?: string;
     /** Maximum number of pages to discover & scan */
@@ -1494,7 +1809,7 @@ declare function defineConfig(config: AgentLighthouseConfig): AgentLighthouseCon
  */
 declare function loadConfigFile(customPath?: string): AgentLighthouseConfig;
 
-type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
 declare class Logger {
     level: LogLevel;
     private shouldLog;
@@ -1516,4 +1831,4 @@ type AcpLinkType = (typeof ACP_LINK_TYPES)[number];
  */
 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 };
+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_ORIGIN_CACHE_MAX_ENTRIES, DEFAULT_ORIGIN_CACHE_TTL_MS, DEFAULT_SCAN_LIMIT, type DeprecationNotice, DeprecationNoticeSchema, type EvidenceGrade, EvidenceGradeSchema, type EvidenceKey, EvidenceKeySchema, type ExpectedKind, type FetchClass, type FetchOptions, type FetchResult, type FetcherOptions, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, ORIGIN_EVIDENCE_VERSION, OriginCache, type OriginCacheOptions, type OriginEvidence, PAGE_TYPE_LABELS, PHASE_WEIGHTS, PRESETS, type PageContext, type PageCss, type PageJudgement, type PageOverride, type PageType, PageTypeSchema, 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 ScanConditions, ScanConditionsSchema, 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, boundedDispatcher, buildCategoryResult, buildScanEvidence, calculateCategoryScore, calculateOverallScore, classifyFetch, classifyResponse, collectPageCss, collectSitemapEntries, computeOriginCacheKey, createFetcher, defaultConfig, defaultOriginCache, 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, shouldBypassOriginCache, stripBom, topLevelJsonLd, traceFromCheck, weightForGrade };