@forkpoint/agent-lighthouse-core 3.1.0 → 4.1.0

package/dist/index.d.mts

@@ -2,12 +2,13 @@ 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). */
@@ -57,11 +58,6 @@ interface FetchResult {
     }>;
     error?: 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.
- */
-declare function isSafeUrl(url: string): Promise<boolean>;
 interface FetcherOptions {
     /**
      * undici dispatcher for every request this fetcher makes.
@@ -89,6 +85,10 @@ interface FetcherOptions {
      * is the origin.
      */
     maxConcurrent?: number;
+    /**
+     * Extra HTTP headers sent with every request from this fetcher.
+     */
+    headers?: Record<string, string>;
 }
 /**
  * A dispatcher that opens at most `connections` sockets per origin.
@@ -105,7 +105,7 @@ declare function createFetcher(fetcherOptions?: FetcherOptions): {
 
 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;
@@ -127,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.
@@ -137,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).
@@ -153,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;
@@ -168,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. */
@@ -180,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;
@@ -194,6 +194,7 @@ interface AuditMeta {
     description: string;
     scoreDisplayMode: ScoreDisplayMode;
     weight: number;
+    pageTypes?: PageType[];
     applicablePageTypes?: PageType[];
     defaultPriority: CheckPriority;
     guidance?: AuditGuidance;
@@ -223,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;
@@ -248,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;
@@ -298,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.
  *
@@ -349,6 +352,47 @@ 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>;
+    };
+    /** The wall-clock budget the scan ran under, and whether it ran out. */
+    budget?: {
+        limitMs: number;
+        elapsedMs: number;
+        exhausted: boolean;
+        /** Audits reported `na` because the budget ran out before they started. */
+        skippedCount: number;
+    };
 }
 interface ReadinessVitals {
     commerce: number;
@@ -357,6 +401,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.
  *
@@ -394,7 +486,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[];
@@ -405,6 +497,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). */
@@ -437,6 +530,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.
      *
@@ -445,6 +547,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>;
 
@@ -498,7 +610,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 {
@@ -571,9 +683,10 @@ interface AuditTrace {
      * `ran` — the audit executed and returned.
      * `skipped` — no scanned page matched its `applicablePageTypes`.
      * `gated` — the scan never obtained evidence the audit needs.
+     * `budget` — the scan's wall-clock budget ran out before it started.
      * `error` — it threw, or its result was rejected by the schema.
      */
-    outcome: 'ran' | 'skipped' | 'gated' | 'error';
+    outcome: "ran" | "skipped" | "gated" | "budget" | "error";
     status: CheckStatus;
     score: number;
     weight: number;
@@ -585,10 +698,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. */
@@ -604,10 +717,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;
 };
@@ -620,53 +733,69 @@ 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.**
      *
-     * The orchestrator turns this on for every scan
-     * (`enforceEvidenceGate ?? true`), so an audit's `requires` decides what a
-     * blocked or client-rendered scan reports. It defaults to off in this option
-     * bag only so a caller planning audits directly gets the unfiltered set;
-     * passing `false` is the measurement escape hatch for comparing a gated run
-     * against an ungated 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[];
+};
+/** A budget as a sentence names it: whole seconds, or milliseconds under one. */
+declare function formatBudget(ms: number): string;
+/** What an aborted budget signal says, for the stub that names it. */
+declare function budgetReason(signal: AbortSignal): string;
 /**
  * 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.
+ *
+ * `budget` is the scan's wall-clock budget. Once it is aborted, no further
+ * audit is constructed, and none that was still running is believed: both
+ * report `na` tagged {@link TAG_SKIPPED_SCAN_BUDGET}. The running one is
+ * withheld because a request the budget refused answers with an error, and
+ * an audit reads that error as a broken link or a missing artifact. That
+ * would be a claim about the clock, not about the site.
  */
-declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan, onTrace?: AuditTraceHandler): Promise<AuditRunResult>;
+declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan, onTrace?: AuditTraceHandler, budget?: AbortSignal): 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;
@@ -674,20 +803,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;
@@ -734,7 +863,22 @@ declare class ProgressTracker {
 interface ScanOptions {
     onEvent?: (event: ScanEvent) => void;
     pages?: PageOverride[] | null;
+    /** Explicitly declared page type for the target URL. */
+    pageType?: PageType;
+    /**
+     * The caller's cancellation. Aborting it makes `runScan` throw; the scan
+     * budget below never does.
+     */
     signal?: AbortSignal;
+    /**
+     * Wall-clock budget for the whole scan, in milliseconds. Defaults to
+     * {@link SCAN_TIMEOUT_MS}. When it runs out the scan finishes with what it
+     * has: requests in flight abort, no further request is sent, and every
+     * audit not yet started, or still running when it went, reports `na`
+     * tagged `skipped:scan-budget`. `conditions.budget` on the report records
+     * it. `0` disables the budget.
+     */
+    timeoutMs?: number;
     /**
      * 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.
@@ -757,48 +901,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.
-     *
-     * Omitted, the scan uses the fetcher's shared agent, which opens as many
-     * connections per origin as the scan asks for. A caller scanning origins that
-     * did not invite it — the nightly corpus job — passes a bounded agent so the
-     * ~28 root-file requests the scan issues at once do not arrive at a stranger's
-     * WAF as a burst.
      */
     dispatcher?: Dispatcher;
     /**
      * How many requests this scan may have in flight at once.
-     *
-     * Omitted, the scan issues every request as it reaches the fetcher. A caller
-     * scanning origins that did not invite it sets this alongside `dispatcher`:
-     * the dispatcher bounds the sockets, and this bounds what is issued, so the
-     * requests the scan holds back wait outside the per-request deadline and
-     * outside `ttfbMs` instead of inside undici's queue. Without it a bounded
-     * scan reports its own queueing as the origin being slow or unreachable.
      */
     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.
-     *
-     * For a caller that must read `robots.txt` before it decides to scan at all.
-     * The nightly corpus job is one: it asks permission first, and without this
-     * every site it visits gets two requests for the one file its owner watches.
-     * It must be the response to `<baseUrl>/robots.txt` fetched with this
-     * scanner's own user agent — anything else and the scan judges a file it was
-     * not served.
      */
     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;
 /**
@@ -814,7 +951,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 {
@@ -888,7 +1025,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;
@@ -955,6 +1092,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
@@ -969,6 +1110,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
@@ -978,6 +1124,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.
@@ -997,7 +1144,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.
@@ -1162,17 +1309,35 @@ 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;
+/**
+ * Wall-clock budget for one scan. When it runs out, requests in flight are
+ * aborted, no further request is sent, and every audit not yet started is
+ * reported `na` tagged `skipped:scan-budget`. 180 s clears the 95th
+ * percentile of the curated corpus (109 s on 2026-09-02) with margin; the
+ * scans it cuts ran 5 to 17 minutes.
+ */
+declare const SCAN_TIMEOUT_MS = 180000;
 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";
 declare const TAG_SCAN_ERROR = "scan-error";
 /** An audit the scan could not feed: it needs evidence this scan never got. */
 declare const TAG_SKIPPED_NO_EVIDENCE = "skipped:no-evidence";
+/** An audit the scan never started: its wall-clock budget ran out first. */
+declare const TAG_SKIPPED_SCAN_BUDGET = "skipped:scan-budget";
 /** Display names for the 8 v2 categories. */
 declare const CATEGORY_NAMES: Record<string, string>;
 declare const READINESS_WEIGHTS: {
@@ -1200,7 +1365,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.
@@ -1212,6 +1377,12 @@ declare function calculateCategoryScore(checks: CheckResult[]): number;
  */
 declare function buildCategoryResult(id: string, checks: CheckResult[], mass?: number): CategoryResult;
 declare function calculateOverallScore(categories: CategoryResult[]): number;
+/**
+ * How much of the registry's evidence mass the checks carrying `tag` hold.
+ * The gate and the scan budget both stub audits as `na` under their own
+ * tag, and each is judged against {@link GATED_MASS_UNSCORED_THRESHOLD}.
+ */
+declare function skippedMassShare(checks: CheckResult[], tag: string): number;
 
 /**
  * Read product fields straight from the scanned product page(s)' structured
@@ -1332,6 +1503,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<{
@@ -1382,6 +1554,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;
@@ -1408,6 +1581,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;
@@ -1526,13 +1700,156 @@ 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;
+    }>;
+    budget: z.ZodOptional<z.ZodObject<{
+        limitMs: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+        exhausted: z.ZodBoolean;
+        skippedCount: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        limitMs: number;
+        elapsedMs: number;
+        exhausted: boolean;
+        skippedCount: number;
+    }, {
+        limitMs: number;
+        elapsedMs: number;
+        exhausted: boolean;
+        skippedCount: 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;
+    };
+    budget?: {
+        limitMs: number;
+        elapsedMs: number;
+        exhausted: boolean;
+        skippedCount: number;
+    } | undefined;
+}, {
+    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;
+    };
+    budget?: {
+        limitMs: number;
+        elapsedMs: number;
+        exhausted: boolean;
+        skippedCount: number;
+    } | undefined;
+}>;
 
 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;
@@ -1555,11 +1872,13 @@ 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 */
     maxPages?: number;
+    /** Scan budget in seconds; 0 disables it. The flag `--timeout` overrides it. */
+    timeout?: number;
 }
 /** Helper function for type-safe configuration files */
 declare function defineConfig(config: AgentLighthouseConfig): AgentLighthouseConfig;
@@ -1568,7 +1887,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;
@@ -1590,4 +1909,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 FetcherOptions, 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, boundedDispatcher, 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, TAG_SKIPPED_SCAN_BUDGET, type UaProbe, type WafProtection, allEvidenceMet, allJsonLdNodes, boundedDispatcher, budgetReason, 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, formatBudget, 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, skippedMassShare, stripBom, topLevelJsonLd, traceFromCheck, weightForGrade };