@reddoorla/maintenance 0.90.1 → 0.91.0

package/dist/prospect/types.d.ts

@@ -1,5 +1,642 @@
 import { a as AuditResult } from '../types-OIQZ5hWN.js';
 
+/**
+ * Who does the engine actually answer this category with?
+ *
+ * `visibilityScore` alone is close to useless as a report headline: across the
+ * 12 audits stored to date it is 0 for eight of them and takes only four
+ * distinct values in total, so it cannot rank two thirds of prospects against
+ * each other at all. Worse, a bare 0 invites the one question we cannot
+ * honestly answer — "how do we make it go up?"
+ *
+ * What IS honest, and what a prospect can act on, is the shape of the answer
+ * they are absent from. Two zeros mean opposite things:
+ *
+ *   - Revogen scores 0, and the engine answers their category with Stryker,
+ *     Arthrex, Conmed, Globus, NCBI and the FDA. No website edit puts anyone
+ *     in that answer. The honest advice is to not buy AEO at all.
+ *   - Beachfront Dentistry scores 0, and the engine answers "dentist in
+ *     Redondo Beach CA" with Yelp plus five other local practices' own
+ *     websites — businesses exactly their size. Being in that answer is
+ *     plainly possible; they simply are not.
+ *
+ * Same number, opposite counsel. This module computes the evidence that tells
+ * them apart. Everything here is arithmetic over citations the engine actually
+ * returned — no judgment, no weighting, nothing we chose. A label sits on top
+ * of it elsewhere; the numbers below are what the label has to survive.
+ */
+type SourceCount = {
+    domain: string;
+    /** Total citations, counting repeats within a single answer. */
+    count: number;
+    /** `count` as a fraction of every category citation, 0..1. */
+    share: number;
+};
+type AnswerSpace = {
+    /** Category answers that produced at least one citation. Answers that cited
+     *  nothing are excluded here but still counted in `queriesAsked` — an engine
+     *  that declined to cite anything is a fact about the query, not about the
+     *  prospect, and folding it into the shares would dilute them with silence. */
+    answersWithCitations: number;
+    queriesAsked: number;
+    /** Every citation across every category answer, repeats included. */
+    citationsTotal: number;
+    /** Distinct domains behind those citations. The fragmentation headline: on
+     *  the benchmark this ran 53–77 per site across five queries.
+     *
+     *  Scales with how many queries ran, so it is NOT comparable between a
+     *  3-query run and a 5-query run (the early Reddoor audits sit at 14–38 for
+     *  that reason alone, not because their categories are less crowded).
+     *  `medianWidthPerAnswer` is the per-query figure to compare across sites. */
+    distinctDomains: number;
+    /** Ranked, most-cited first. */
+    topSources: SourceCount[];
+    /** How many distinct domains it takes to account for half of all citations.
+     *  This is the number that killed the "get listed in the three directories
+     *  the engine reads" pitch: on the benchmark it ran 10–18, meaning no such
+     *  short list exists to buy your way onto. Null when nothing was cited. */
+    domainsToHalf: number | null;
+    /** Median distinct domains cited within a SINGLE answer — how crowded one
+     *  reply is, as opposed to the category across five of them. Null when no
+     *  answer cited anything. */
+    medianWidthPerAnswer: number | null;
+    /** 1-based position of the prospect's own domain in `topSources`, or null
+     *  when it was never cited.
+     *
+     *  An earlier read of a 9-site benchmark held that every site scoring above
+     *  zero was the TOP source in its own category. At 12 sites that breaks:
+     *  Ludlow Kingsley scores 40 from rank 4. Being cited at all is what tracks
+     *  the score — which is very nearly a restatement of how the score is
+     *  computed, so this field is evidence for the reader, not an independent
+     *  finding. Do not build a claim on rank 1. */
+    ownDomainRank: number | null;
+    ownDomainCount: number;
+    /** The most-cited source that is NOT the prospect, on the queries we ran.
+     *
+     *  ⚠️ This is NOT "who owns your category", and the report must never call
+     *  it that. Real shares from the benchmark: across the audited sites the
+     *  biggest rival held 4%, 6% and 8% of citations. At those shares there is
+     *  no owner —
+     *  the answer space is fragmented (see `domainsToHalf`, which ran 5–18).
+     *  What this legitimately answers is narrower and still useful: "on the
+     *  specific searches we ran, here is who came back instead of you."
+     *  The character of the whole source list — local practices vs. Stryker and
+     *  the FDA — is the actual finding; no single row carries it. */
+    topRival: SourceCount | null;
+};
+
+/**
+ * What is broken, and what is heavy.
+ *
+ * Lighthouse audits one page and scores it. It does not crawl, so it never sees
+ * a link that 404s three pages in, and it reports a performance number without
+ * naming the four-megabyte hero image that caused it. Both of those are the
+ * actionable half: "your performance is 60" is a grade, "this one photograph is
+ * 4.2 MB and it is on every page" is a job.
+ *
+ * Everything here costs requests to someone else's server, so it is bounded and
+ * paced, and the bounds are reported. `linksFound` against `linksChecked` is
+ * how the report avoids saying "every link works" when it tested forty of two
+ * hundred — the same discipline as `anchorCount` in the extract.
+ *
+ * SSRF: every URL probed here came out of the prospect's markup, which means an
+ * attacker who controls the page controls what we fetch. `isPrivateOrLoopbackHost`
+ * is the same guard the crawler applies to its own entry point and redirects,
+ * and it is applied here for the same reason.
+ */
+type ProbedUrl = {
+    url: string;
+    /** HTTP status, or null when the request itself failed. Those are different
+     *  claims: a 404 is the prospect's broken link, a transport failure might be
+     *  our network, and only the first belongs in a report as their defect. */
+    status: number | null;
+    /** Size in bytes, from `content-length`. Null when the server did not say —
+     *  which is common, and is reported as unknown rather than guessed at. */
+    bytes: number | null;
+    error: string | null;
+    /** Crawled pages that reference it, so a fix has an address. */
+    referencedBy: string[];
+};
+/**
+ * Why a probe produced no evidence about the prospect's site.
+ *
+ * Every value here is OUR missing data, never their defect — which is the whole
+ * reason the type exists. Grouped rather than free text so a report can count
+ * them and a test can assert on them.
+ *
+ *   auth-required  401. The URL exists and is gated; a visitor with an account
+ *                  sees it and we do not.
+ *   refused        403. Overwhelmingly bot management, not a dead URL — a CDN
+ *                  declining a non-browser client for an image the page paints
+ *                  perfectly well.
+ *   rate-limited   429. We caused this one, by asking too fast.
+ *   server-error   5xx. The server was having a bad moment when we asked;
+ *                  saying so as "your link is broken" outlives the moment.
+ *   no-response    The request never got an answer at all — possibly our
+ *                  network, possibly a timeout we set.
+ *   other          Any other non-2xx we are not willing to characterise.
+ */
+type UnverifiedReason = "auth-required" | "refused" | "rate-limited" | "server-error" | "no-response" | "other";
+type UnverifiedGroup = {
+    reason: UnverifiedReason;
+    count: number;
+    /** A sentence a report can print as-is, phrased as our limit rather than
+     *  their fault. */
+    detail: string;
+    /** One URL from the group, so a reader can reproduce it themselves. */
+    example: string;
+};
+/** The half of the probe budget that came back without evidence. Reported
+ *  beside the broken lists, never inside them: "we could not check 6 of your
+ *  40 links" is an honest sentence, and "6 broken links" would have been a
+ *  false one. */
+type UnverifiedProbes = {
+    count: number;
+    groups: UnverifiedGroup[];
+};
+type AssetCheck = {
+    /** Internal links that did not resolve to something a visitor can read.
+     *  Only answers that prove absence — see `classifyProbe`. */
+    brokenLinks: ProbedUrl[];
+    /** Images that did not load. A broken image is visible to every visitor and
+     *  is usually a one-line fix, which makes it the cheapest finding here. */
+    brokenImages: ProbedUrl[];
+    /**
+     * Links we asked about and learned nothing from.
+     *
+     * Optional because this type also describes runs deserialized from
+     * `prospect_audits.result_json`, and every report stored before this field
+     * existed lacks it — and lacks it for the worst reason: in those reports the
+     * unverifiable answers are sitting in `brokenLinks`. `checkAssets` always
+     * sets it; a reader must treat absence as "not measured", never as "nothing
+     * went unverified".
+     */
+    linksUnverified?: UnverifiedProbes;
+    /** Images we asked about and learned nothing from. Optional for the same
+     *  reason as `linksUnverified`, and with the same reading of absence. */
+    imagesUnverified?: UnverifiedProbes;
+    /** Heaviest images first, capped — the ones worth naming. */
+    heaviestImages: ProbedUrl[];
+    /** Summed `content-length` of every image we got a size for. Null when no
+     *  image reported one, so the report never prints "0 MB of images" for a
+     *  page full of pictures whose server is quiet about sizes. */
+    imageBytesMeasured: number | null;
+    /** How many images contributed to that sum, against how many were checked —
+     *  the honest denominator for it. */
+    imagesWithKnownSize: number;
+    linksFound: number;
+    linksChecked: number;
+    imagesFound: number;
+    imagesChecked: number;
+};
+
+/**
+ * What one AI crawler gets when it asks for the homepage, next to what a
+ * browser gets.
+ *
+ * `blocked` is always a COMPARISON — a site that is down answers everyone
+ * badly, and that is an outage, not a crawler policy — and it is now also
+ * always CONFIRMED: two requests had to agree before this is true. The finding
+ * it supports is "this agent is served something a browser is not", which is
+ * what we actually observed. It is not "the site blocks this vendor": bot
+ * management keys on IP reputation, geography and rate as well as the header,
+ * none of which we can characterise from here.
+ */
+type CrawlerReach = {
+    agent: string;
+    /** The last status we saw, or null when no request got an answer. */
+    status: number | null;
+    /** Confirmed served differently from a browser. Only ever true when
+     *  `measured` is true. */
+    blocked: boolean;
+    /**
+     * Do we have evidence either way about this agent?
+     *
+     * False for a transient answer (429, 5xx), a failed request, or two requests
+     * that disagreed. Each of those is OUR missing data — most obviously the 429,
+     * which our own request rate causes — and a report must say "not measured"
+     * rather than name a vendor on the strength of it.
+     *
+     * Optional because this type also describes runs deserialized from
+     * `prospect_audits.result_json`, and every report stored before this field
+     * existed lacks it — those `blocked` values came from a single unpaced
+     * sample. `checkCrawlerReach` always sets it; a reader must treat absence as
+     * "we do not know how this was judged".
+     */
+    measured?: boolean;
+    /** Why we could not judge it, in words a report can print. Null when
+     *  `measured` is true, absent on reports stored before it existed. */
+    unverifiedReason?: string | null;
+    error: string | null;
+};
+type CrawlerReachability = {
+    /** False when the browser control itself failed or came back 4xx/5xx, so
+     *  nothing below can be attributed to crawler policy and the report must say
+     *  "not measured". */
+    measured: boolean;
+    browserStatus: number | null;
+    agents: CrawlerReach[];
+    /** Agents confirmed to be served something a browser is not. The finding —
+     *  and it is a description of what we saw, never an accusation about intent. */
+    blocked: string[];
+    /** Agents we asked about and learned nothing from. Neither reachable nor
+     *  blocked: not measured, and reported as such so the report's denominator is
+     *  honest. Optional for reports stored before it existed, where absence means
+     *  "not measured" rather than "nothing went unverified". */
+    unverified?: string[];
+};
+/** One reachability answer. `measured: false` means the request failed for a
+ *  reason that is ours or the network's, not the site's — and a report must say
+ *  "not measured" rather than convert our own failure into their defect. */
+type Reachability = {
+    measured: boolean;
+    /** What was requested, so the finding has an address the reader can try. */
+    url: string;
+    ok: boolean;
+    /** Where it landed, when it landed anywhere. */
+    landedOn: string | null;
+    error: string | null;
+};
+type BasicsCheck = {
+    /**
+     * Typing the address without `https://`. Browsers still default to plain
+     * http for a bare hostname in plenty of places — a pasted link in a text
+     * message, an old bookmark, a printed card — and a site that does not
+     * redirect either shows a "Not secure" warning or does not answer at all.
+     */
+    insecureEntry: Reachability;
+    /**
+     * The other of www / apex. Whichever one the site does not use, somebody
+     * types anyway; if it has no DNS record the visitor gets a browser error page
+     * with the site's name on it.
+     */
+    hostVariant: Reachability & {
+        host: string;
+    };
+    /**
+     * A URL that cannot exist. Two things can be wrong: the server answers 200
+     * (a "soft 404" — search engines index the junk and a mistyped link looks
+     * like a real page), or it answers 404 with a bare server error page carrying
+     * no way back into the site.
+     */
+    notFound: Reachability & {
+        status: number | null;
+        /** Did the response carry any link back into the site? A default nginx or
+         *  Apache error page carries none, and a visitor who lands there leaves. */
+        linksBackToSite: boolean;
+    };
+    /**
+     * Images loaded over plain http on an https page. Browsers block or refuse to
+     * upgrade these, so they are broken images for some visitors and a mixed-
+     * content warning for the rest. `measured` is false when the site is not on
+     * https at all, in which case `insecureEntry` is the finding instead.
+     */
+    mixedContent: {
+        measured: boolean;
+        imageUrls: string[];
+        imagesSeen: number;
+    };
+    /** Alt text coverage across the pages examined. An image counted once per page
+     *  it appears on — the ratio is the honest reading, not the totals. */
+    altText: {
+        imagesTotal: number;
+        imagesWithAlt: number;
+        pagesExamined: number;
+    };
+    /** Titles used by more than one page. The browser tab, the bookmark and the
+     *  search result all show this text, and repeating it makes them
+     *  indistinguishable. */
+    duplicateTitles: {
+        title: string;
+        pages: string[];
+    }[];
+    /**
+     * What each AI crawler is actually served, as opposed to what robots.txt says
+     * it may have.
+     *
+     * These are different questions and the audit used to answer only the first
+     * while reporting the second. robots.txt is a request the site publishes; a
+     * CDN's bot management is an answer it enforces, and the second can contradict
+     * the first without the owner knowing. Verified on a live prospect: see the
+     * note on CRAWLER_AGENTS.
+     *
+     * Undefined on reports stored before this existed — absence is "not measured",
+     * never "nothing blocked".
+     */
+    crawlerReachability?: CrawlerReachability;
+};
+
+/**
+ * Does the site tell the same story on every page?
+ *
+ * Two findings live here, and they share a property that makes them worth
+ * checking together: each is cheap to fix, embarrassing to leave, and invisible
+ * from any single page. You only see them by comparing pages, which is exactly
+ * what nobody does when they look at their own site.
+ *
+ *   - A stale copyright year. It says nobody has touched this in years, to
+ *     every visitor, on every page, for free.
+ *   - Pages that do not share the site's navigation. Usually a landing page
+ *     built outside the template — a visitor who lands there is in a different
+ *     website with no way back into this one.
+ *
+ * The contact numbers and addresses are an INVENTORY, not a third finding, and
+ * that is a correction rather than an omission. This module used to treat more
+ * than one phone number as "a business that disagrees with itself". Replayed
+ * over every stored audit, that rule failed 8 of 22 sites and every single hit
+ * was legitimate: our own site's labelled California and Texas office lines, a
+ * nonprofit listing thirteen partner helplines on a resources page, a company's
+ * fax line, a firm publishing separate general and business-inquiry numbers. A
+ * business with two numbers is not confused; it has two numbers. The count was
+ * correct data and the claim built on it was false, which is the worst of both
+ * — and it was refutable by the reader from their own contact page.
+ *
+ * What survives is real and actionable: WHICH numbers appear, on which pages,
+ * and whether each was ever written as a `tel:` link (see `linked`). Consumers
+ * must render the list as a receipt. Any future "you have too many numbers"
+ * finding needs a way to tell a second office from a contradiction first, and
+ * this data does not carry one.
+ *
+ * Deliberately NOT checked: the postal address. Addresses cannot be pulled out
+ * of free text reliably enough to accuse someone of inconsistency, and a false
+ * positive here would have a prospect checking a page that is perfectly fine.
+ * When a site publishes a `PostalAddress` in its schema we already read it; a
+ * text scrape would be a guess wearing a finding's clothes.
+ */
+type ContactVariant = {
+    /** Digits only for a phone, lower-cased for an email — what makes two
+     *  spellings of the same thing compare equal. */
+    normalized: string;
+    /** Every spelling actually seen, so the report shows the receipts rather
+     *  than asserting a mismatch the reader cannot check. */
+    seenAs: string[];
+    pages: string[];
+    /**
+     * Was it ever written as a `tel:` / `mailto:` link, anywhere on the site?
+     *
+     * False means the number exists only as prose. On a phone — which is where
+     * most people read a number and where the intent to call is highest — that is
+     * a piece of text you cannot tap, and the visitor has to memorise it and
+     * switch apps. It is a one-attribute fix, and it is invisible from a desktop,
+     * which is exactly where nobody looks.
+     *
+     * Optional: reports stored before this was recorded lack it, and a reader must
+     * treat its absence as "not measured" rather than as "not a link".
+     */
+    linked?: boolean;
+};
+type ConsistencyResult = {
+    phones: ContactVariant[];
+    emails: ContactVariant[];
+    /** Every copyright year found in page text, ascending. Empty when the site
+     *  publishes no copyright line at all, which is not a defect. */
+    copyrightYears: number[];
+    /** The newest year found, or null when none was. */
+    newestCopyrightYear: number | null;
+    /** Pages carrying none of the site's shared navigation links. Empty when
+     *  there is no shared navigation to compare against — see `sharedNavLinks`. */
+    pagesOffTemplate: string[];
+    /** How many links appear on EVERY page examined. This is the site's shared
+     *  navigation, derived rather than assumed: no `<nav>` element is required,
+     *  because plenty of sites do not use one. */
+    sharedNavLinks: number;
+    pagesExamined: number;
+};
+
+/**
+ * Is this cited domain someone else's, or another one of the prospect's own?
+ *
+ * Built after getting it wrong. The accuracy stage read every cited domain that
+ * was not the prospect's as "somewhere else the engine looked", and on the first
+ * real run that produced the finding "an AI describes your practice using
+ * dochopkins.com, cited four times against one citation of your own site" —
+ * which was true except for the part that mattered: dochopkins.com is theirs
+ * too, an old site they never took down.
+ *
+ * Getting this backwards is expensive in both directions. Calling a client's own
+ * legacy site "a third party" is a factual error about their business, in a
+ * document arguing that factual errors about their business are the problem.
+ * And the corrected finding is the better one anyway: an engine preferring your
+ * old site to your current one is a concrete thing to fix, where "a directory
+ * outranks you" often is not.
+ *
+ * A shared phone number is the signal. Businesses change domains, names and
+ * copy; the number on the door tends to survive all three, and two sites
+ * publishing the same number are almost never unrelated. A redirect onto the
+ * prospect's own host settles it outright.
+ */
+/**
+ * Four answers, because three of them lead somewhere different.
+ *
+ * `yours` — your site, or another domain you own. Fixable by you today.
+ * `platform` — a directory, review site or social profile. A listing ABOUT you
+ *   that you can usually claim and correct, which is a different job from
+ *   writing a page and worth naming separately.
+ * `theirs` — no connection to the prospect that we could find.
+ *
+ *   Worded deliberately as an absence of evidence, because that is all this
+ *   module establishes: no shared phone number, and no redirect home. It is
+ *   NOT a finding that the domain belongs to somebody else — asserting that
+ *   about a third party is a claim we cannot check, in a report whose whole
+ *   argument is that unchecked claims are the problem. The user-facing string
+ *   lives in `because` and says so; the variant name is kept because
+ *   `DomainVerdict` already crosses a module boundary into accuracy.ts, and
+ *   nothing renders the name itself.
+ * `unknown` — we could not tell, and say so.
+ */
+type DomainOwner = "yours" | "platform" | "theirs" | "unknown";
+type DomainVerdict = {
+    domain: string;
+    owner: DomainOwner;
+    /** What decided it, in words a client can check. */
+    because: string;
+};
+
+type AssertionVerdict = "confirmed" | "contradicted" | "absent" | "unverified";
+type Assertion = {
+    /** The statement, in plain words. */
+    claim: string;
+    verdict: AssertionVerdict;
+    /** Verbatim from the engine's answer — verified as a real substring of it. */
+    engineQuote: string;
+    /** Verbatim from the prospect's own site, verified. Null when there is none. */
+    siteQuote: string | null;
+    /** Why we could not judge it. Null unless the verdict is `unverified`. */
+    unverifiedReason: string | null;
+    /**
+     * Something related the site DOES say, on an assertion we are still calling
+     * absent — the obvious objection, answered before it is raised.
+     *
+     * The case this exists for, from a real run: an engine said a practice was
+     * "formerly known as <a person's name> DDS"; the site never says that, but
+     * its team page lists a clinician with a similar name. Suppressing the
+     * finding loses the most valuable line in the section. Printing it bare
+     * invites a client to open their own team page and conclude we cannot read.
+     * Printing it with "your site mentions <the name it does list>, but not
+     * this" keeps the finding and shows the work.
+     */
+    nearbyMention: string | null;
+    /** Domains the engine cited on the answer this came from, excluding the
+     *  prospect's own — who it was reading instead. */
+    sourceDomains: string[];
+    /** Which branded query produced it. */
+    query: string;
+    engine: string;
+};
+type AccuracyResult = {
+    assertions: Assertion[];
+    /**
+     * Who owns each domain the engine cited.
+     *
+     * Kept beside the assertions rather than copied into each one: the same domain
+     * backs several claims, and a verdict about who owns a website should exist in
+     * exactly one place. Without this the report called a client's own abandoned
+     * site "somewhere else the engine looked" — a factual error about their
+     * business, inside a document about factual errors about their business.
+     */
+    sources: DomainVerdict[];
+    /** False when the site was too large to send whole. Every `absent` verdict is
+     *  suppressed to `unverified` when this is false, because "the site does not
+     *  say it" is not a claim we can make about pages we did not read. */
+    siteFullyRead: boolean;
+    pagesRead: number;
+    pagesTotal: number;
+    /** Which branded answers we had full text for. A run whose probes predate
+     *  `fullAnswer` reports zero and no assertions, rather than "nothing wrong". */
+    answersRead: number;
+};
+
+/**
+ * Can a visitor do the one thing this site needs them to do?
+ *
+ * Every other check in this audit is generic — crawlable, readable, not broken.
+ * Those are worth measuring and they are the same questions for every site,
+ * which is exactly the problem: a dentist's site succeeds when somebody books an
+ * appointment and a branding studio's succeeds when a qualified enquiry arrives
+ * with a budget attached. Grading both against one template scores neither
+ * against what it is for.
+ *
+ * So one goal is named, and the findings are read against it. The goal is
+ * inferred from the site by the analyze stage and may be overridden by the
+ * operator — and an inference we get wrong is itself worth reporting, because if
+ * a model that has just read twenty pages cannot tell what the site is for,
+ * neither can a visitor.
+ *
+ * Findings carry a `scope`, and the report orders by it. That ordering is the
+ * only place the commercial ladder appears: a stale phone link is an afternoon,
+ * "you have never published a price and every buyer asks" is a content
+ * engagement, and "there is no way to publish or update any of this" is a
+ * platform conversation. The report must never say those words. Ordering does
+ * the work, and a prospect who reads to the bottom arrives at the conversation
+ * on their own.
+ */
+type SiteGoal = "book" | "enquire" | "call" | "visit" | "buy" | "demo" | "partner" | "unknown";
+declare const GOAL_LABELS: Record<SiteGoal, string>;
+/** How much work putting one thing right is. Orders the report; never printed
+ *  as a tier, and never priced. */
+type Scope = "quick" | "content" | "structural";
+/**
+ * Three states, not two — and the third is the one that matters.
+ *
+ * Caught on live data: `reachable` and `tappable-phone` both read their input
+ * from `checks`, which older stored reports do not carry. With a boolean they
+ * came back `false`, and the report said "no way to reach you from where they
+ * land" about sites that have one — turning our own missing measurement into
+ * the prospect's defect. That is the single error this whole codebase is built
+ * not to make, and a two-state field makes it the default.
+ */
+type RequirementStatus = "met" | "missing" | "unmeasured";
+type GoalRequirement = {
+    key: string;
+    /** What the visitor needs, in the visitor's terms. */
+    label: string;
+    status: RequirementStatus;
+    /** Where we found it — the receipt. Null when we did not. */
+    evidence: string | null;
+    /** Why this one matters for THIS goal, not in general. */
+    why: string;
+    scope: Scope;
+};
+type GoalFit = {
+    goal: SiteGoal;
+    /** "operator" when supplied at dispatch, "inferred" when the analyze stage
+     *  read it off the site. A reader is owed that distinction. */
+    source: "inferred" | "operator";
+    requirements: GoalRequirement[];
+    met: number;
+    /** Requirements we could actually judge — `met` + `missing`. Excludes
+     *  `unmeasured`, so "3 of 4" never counts something we did not look at. */
+    total: number;
+};
+declare function orderRequirements(reqs: GoalRequirement[]): GoalRequirement[];
+
+/**
+ * Can a visitor actually get from where they landed to a way of contacting you?
+ *
+ * Everything else in this audit measures whether a site can be found and read.
+ * This measures whether it can be ACTED ON, which is the part that decides
+ * whether traffic becomes a phone call.
+ *
+ * The measurement that matters is click distance, and it matters because of
+ * where visitors actually land. A search engine — and an answer engine citing a
+ * page — sends people to a deep page, not the homepage. A site whose only
+ * contact form sits behind the homepage nav is asking a stranger who arrived on
+ * a blog post to go looking. Some do. Most leave.
+ *
+ * So this builds a link graph across the pages the crawl retrieved, finds every
+ * way of making contact on each one, and walks outward to find how far the
+ * nearest one is. A page with no path at all is a dead end, and a dead end is a
+ * defect with a price attached.
+ *
+ * The honest limit, which every consumer must carry into what it prints: the
+ * crawl retrieves a handful of pages, not the whole site. "Dead end" here means
+ * "no path among the pages we looked at" — real, worth reporting, and not the
+ * same claim as "no path exists". `pagesExamined` is reported so the sentence
+ * can say which one it means.
+ */
+type AffordanceKind = "form" | "tel" | "mailto";
+type ContactAffordance = {
+    kind: AffordanceKind;
+    /** The crawled page it was found on. */
+    page: string;
+    /** The number, the address, or the form's action — the receipt. */
+    detail: string;
+};
+type PageJourney = {
+    url: string;
+    /** Clicks to the nearest page carrying a contact affordance. 0 means it is on
+     *  this page; null means no path was found among the pages examined. */
+    clicksToContact: number | null;
+    /** Links from this page to other pages the crawl retrieved. Zero means a
+     *  visitor who lands here can go nowhere, which is a different and worse
+     *  problem than merely being far from the contact page. */
+    internalLinks: number;
+};
+type JourneyMap = {
+    affordances: ContactAffordance[];
+    pages: PageJourney[];
+    /** Pages with no path to any contact affordance, among those examined. */
+    deadEnds: string[];
+    /** The worst distance among pages that DO have a path — the honest headline,
+     *  because an average hides the one page that strands people. Null when no
+     *  page has a path. */
+    worstClicksToContact: number | null;
+    /** How many pages this was computed over. Reported so no consumer can
+     *  describe a five-page sample as though it were the whole site. */
+    pagesExamined: number;
+    /**
+     * Did every page examined carry a recorded anchor list?
+     *
+     * False means the crawl did not record links (reports stored before
+     * `PageExtract.anchors` existed), and NOTHING here is a finding: `deadEnds`
+     * is empty and `worstClicksToContact` is null, because a page whose links we
+     * never captured is a page we cannot say anything about. Reading an absent
+     * anchors array as "no links" would report our own missing field as every
+     * page on the site being a dead end.
+     */
+    anchorsMeasured: boolean;
+};
+
 /** Every pipeline stage resolves to this. A failed stage degrades its report
  *  section to "not measured" — it never kills the run (spec: error handling). */
 type StageResult<T> = {
@@ -16,6 +653,53 @@ type RobotsAgentAccess = {
     /** The deciding rule, e.g. "User-agent: GPTBot → Disallow: /". Null = no rule matched. */
     matchedRule: string | null;
 };
+/** One `<a href>`. `href` is exactly as authored — relative, absolute, `tel:`,
+ *  `mailto:`, `#anchor` — and is resolved against the page URL by whoever needs
+ *  an absolute one. Resolving here would discard the distinction between a
+ *  genuinely absolute link and a relative one, which is itself a finding when a
+ *  site hardcodes a staging host. */
+type PageAnchor = {
+    href: string;
+    text: string;
+    rel: string;
+};
+/**
+ * What a form is FOR, inferred from its shape.
+ *
+ * - `enquiry`   asks for a way to reply AND for something else — a name, a
+ *               message, a budget. This is the one that reaches a human.
+ * - `subscribe` asks for a way to reply and nothing else: a lone email box.
+ *               A newsletter signup is a conversion, but it is not a way to
+ *               get an answer, and a visitor with a question is not served by
+ *               one.
+ * - `other`     everything else — search, filters, logins, calculators. No
+ *               attempt is made to tell those apart; the shapes overlap too
+ *               much to do it honestly from markup.
+ *
+ * The distinction earns its keep on real data. One audited site carries a
+ * one-field email box in the footer of every page. Counting that as a contact
+ * route put the whole site at zero clicks from "reaching them", when in fact
+ * the only form that reaches a person was the nine-field one on its contact
+ * page.
+ */
+type FormKind = "enquiry" | "subscribe" | "other";
+/** One `<form>`, in enough detail to tell an enquiry form from a newsletter box
+ *  or a search field. That distinction is the whole point: a site nobody can
+ *  actually reach must not score as though it has a conversion path. */
+type FormShape = {
+    kind: FormKind;
+    /** As authored, or null for a form that posts to its own URL. */
+    action: string | null;
+    /** Lower-cased; defaults to "get", which is what a browser does. */
+    method: string;
+    /** Visible, named controls — hidden inputs, submits and buttons excluded, so
+     *  a one-field newsletter box does not read the same as a real enquiry form. */
+    fieldCount: number;
+    /** Does it ask for an email address or a phone number? A search box does not,
+     *  and this is what separates "can be contacted" from "can be searched". */
+    hasContactField: boolean;
+    hasSubmit: boolean;
+};
 type PageExtract = {
     title: string | null;
     metaDescription: string | null;
@@ -36,6 +720,28 @@ type PageExtract = {
     hasViewportMeta: boolean;
     /** Visible text, whitespace-collapsed. */
     text: string;
+    /**
+     * Anchors in document order, CAPPED — see `anchorCount` for the true total.
+     *
+     * Capped because this whole extract is persisted into
+     * `prospect_audits.result_json`, once per page per audit, and a navigation-
+     * heavy page can carry several hundred anchors. The cap is generous enough
+     * that no ordinary page reaches it.
+     *
+     * The count is reported separately rather than left implicit, because a
+     * truncated list that looks complete is exactly the kind of quiet lie this
+     * audit is built not to tell: "we checked every link" and "we checked the
+     * first 300" are different claims.
+     *
+     * Optional: reports stored before this existed lack it, and a reader must
+     * treat its absence as "not measured" rather than "no links".
+     */
+    anchors?: PageAnchor[];
+    /** True number of `<a href>` on the page, before `anchors` was capped. */
+    anchorCount?: number;
+    /** `src` of each `<img>`, as authored. Same resolution note as `anchors`. */
+    imageSrcs?: string[];
+    forms?: FormShape[];
 };
 type PageCapture = {
     url: string;
@@ -138,10 +844,22 @@ type ChecksResult = {
     llmsTxtMeasured: boolean;
     llmsTxtPresent: boolean;
     viewportOk: boolean;
+    /** Can a visitor get from where they landed to a way of contacting you?
+     *  Optional: reports stored before this was measured lack it, and a reader
+     *  must say "not measured" rather than "no path". See journey.ts. */
+    journey?: JourneyMap;
+    /** Does the site tell the same story on every page? See consistency.ts. */
+    consistency?: ConsistencyResult;
 };
 type BuyerQuestion = {
+    /** Stable key from the fixed set in questions.ts. Absent on reports stored
+     *  before the set was fixed, when the model still wrote its own questions. */
+    id?: string;
     question: string;
-    answered: "yes" | "partial" | "no";
+    /** "unknown" is ours, never the model's: it means we did not get an answer
+     *  for a question we asked, so the row is shown and excluded from the score.
+     *  A missing answer of ours must never be scored as a "no" about them. */
+    answered: "yes" | "partial" | "no" | "unknown";
     /** Is there a passage an AI answer could quote verbatim? */
     quotable: boolean;
     page: string | null;
@@ -153,6 +871,12 @@ type Fix = {
     impact: "high" | "medium" | "low";
     effort: "low" | "medium" | "high";
     tier: "crawl" | "content" | "technical";
+    /** The goal-requirement key this fix would satisfy, when it maps to one —
+     *  the handle `reconcileFixes` uses to drop a fix for something we already
+     *  measured as present. Null is the normal case: most good fixes (a heavy
+     *  image, a broken link, a stale year) answer to no requirement at all.
+     *  Absent on reports stored before the model was asked to tag them. */
+    addresses?: string | null;
 };
 type AnalyzeResult = {
     /** The business's proper name, as a searchable proper noun — "Acme Roofing",
@@ -166,7 +890,15 @@ type AnalyzeResult = {
         score: number;
         missing: string[];
     };
+    /** The one action this site is built to produce — the lens goals.ts reads
+     *  every requirement through. Optional for reports stored before it existed;
+     *  absence means the goal section reads "not measured". */
+    primaryGoal?: SiteGoal;
     buyerQuestions: BuyerQuestion[];
+    /** Which fixed question set was asked — `${goal}-v${QUESTION_SET_VERSION}`.
+     *  Absent on reports stored before the set was fixed. Two audits' Answers
+     *  scores are comparable exactly when this matches; see sameQuestionSet. */
+    questionSetId?: string;
     /** Standalone searches for the visibility probes — what a buyer types before
      *  they know this company exists. Distinct from `buyerQuestions`, which are
      *  phrased about this site and are unanswerable on their own; see the schema
@@ -206,6 +938,21 @@ type ProbeAnswer = {
     citedDomains: string[];
     /** First ~300 chars of the engine's answer — the report's receipt. */
     snippet: string;
+    /**
+     * The engine's answer in full, kept for BRANDED answers only.
+     *
+     * The accuracy stage reads these to work out which statements about the
+     * business its own site actually supports, and a 300-character snippet cuts
+     * off mid-sentence — every claim past it would be invisible, and invisible
+     * reads the same as absent. Branded answers are two or three per run, so
+     * keeping them whole costs little; category and competitor answers are many
+     * and nothing downstream reads them in full, so they do not carry it.
+     *
+     * Optional because reports stored before the accuracy stage existed do not
+     * have it, and there the stage must report that it could not run rather than
+     * report an absence of claims.
+     */
+    fullAnswer?: string;
     /** True when `snippet` is a truncated prefix of a longer answer — set
      *  right where the truncation happens (probes.ts's SNIPPET_CHARS), so the
      *  renderer never has to re-derive "was this cut short?" from a length
@@ -254,6 +1001,31 @@ type ProbesResult = {
         attempted: number;
         answered: number;
     };
+    /**
+     * The shape of the answer the prospect is absent from — see answer-space.ts.
+     *
+     * `visibilityScore` cannot carry a report on its own: across the 12 audits
+     * stored to date it is 0 for eight of them and takes four distinct values in
+     * total, so it cannot rank most prospects against each other at all — and a
+     * bare 0 invites the one question we cannot honestly answer, "how do we make
+     * it go up?". Two zeros can mean opposite things: a category answered by
+     * Stryker, Arthrex and the FDA (no website work reaches that answer — the
+     * honest counsel is not to buy AEO) versus one answered by five local
+     * practices exactly the prospect's size (plainly reachable, and they simply
+     * are not there). This is the evidence that tells those apart.
+     *
+     * Related to `competitorsSeen` but not a replacement for it: that field
+     * predates this one and is what stored reports and the current renderer read,
+     * so it stays. What is new here is the denominator — how many distinct
+     * sources the engine drew on, how many of them it takes to cover half the
+     * citations, and where the prospect's own domain ranks among them.
+     *
+     * Optional because this type also describes runs deserialized from
+     * `prospect_audits.result_json`, and every report stored before this field
+     * existed lacks it. `runVisibilityProbes` always sets it; readers must still
+     * handle its absence rather than assume a stored report has it.
+     */
+    answerSpace?: AnswerSpace;
 };
 type LighthouseScores = {
     performance: number | null;
@@ -303,6 +1075,24 @@ type ProspectAuditResult = {
     lighthouse: StageResult<LighthouseScores>;
     analyze: StageResult<AnalyzeResult>;
     probes: StageResult<ProbesResult>;
+    /** Broken links, broken images and image weight. Its own stage rather than
+     *  part of `checks` because it is the only site check that makes requests —
+     *  `runChecks` is pure and synchronous over the crawl, and it is worth
+     *  keeping it that way. Optional for reports stored before it existed. */
+    assets?: StageResult<AssetCheck>;
+    /** The things a stranger checks first — whether the address works typed the
+     *  ordinary ways, what a missing page does, and the handful of basics the
+     *  crawl already has the evidence for. See basics.ts. Optional for reports
+     *  stored before it existed. */
+    basics?: StageResult<BasicsCheck>;
+    /** Can a visitor do the one thing this site needs them to do? Read against a
+     *  single named goal rather than a generic template — see goals.ts. Optional
+     *  for reports stored before it existed. */
+    goalFit?: StageResult<GoalFit>;
+    /** When an engine describes this business, where is it getting that from —
+     *  each statement sorted by SOURCE, never by truth. See accuracy.ts. Optional
+     *  for reports stored before the stage was wired in. */
+    accuracy?: StageResult<AccuracyResult>;
 };
 
-export type { AnalyzeResult, BuyerQuestion, ChecksResult, CrawlResult, Fix, LighthouseScores, PageCapture, PageExtract, ProbeAnswer, ProbesResult, ProspectAuditResult, RobotsAgentAccess, Scores, StageResult };
+export { type AnalyzeResult, type AnswerSpace, type AssetCheck, type BasicsCheck, type BuyerQuestion, type ChecksResult, type ConsistencyResult, type ContactAffordance, type ContactVariant, type CrawlResult, type Fix, type FormKind, type FormShape, GOAL_LABELS, type GoalFit, type GoalRequirement, type JourneyMap, type LighthouseScores, type PageAnchor, type PageCapture, type PageExtract, type PageJourney, type ProbeAnswer, type ProbedUrl, type ProbesResult, type ProspectAuditResult, type Reachability, type RobotsAgentAccess, type Scope, type Scores, type SiteGoal, type SourceCount, type StageResult, orderRequirements };