` per factor, mirroring `apps/web/src/components/project/PageAuditEvidence.tsx`. The summary\ncarries the name, the page count, and the score, which is everything a reader needs to decide whether to open it. The\nevidence and the fix live together inside, because a problem and its remedy are one thought.\n\nIt used to be two columns, Factors beside Top fixes, built by flattening every recommendation away from the factor it\ncame from and printing the factor's name as the fix's own subtitle. The two columns restated each other, and a\nrecommendation repeated across five sampled pages appeared five times, so one templated problem read as five.\nRecommendations and findings are now deduped onto their factor.\n\nCritical defects sit outside the score, so they render above the list and are never collapsed.\n\n### The waiting state\n\nA check takes about 45 seconds and execution is request-bound, so a native form POST leaves the browser blocked on a\nnavigation for the whole time with nothing on screen but a disabled button. Script intercepts the submit, posts to\n`/api/checks`, and shows `renderLoadingView()` until the id comes back. The work still happens inside that one\nrequest; it is just no longer the thing the browser is painting.\n\n- **It claims only what is knowable while waiting.** The domain and the visitor's own questions are already theirs;\n elapsed time is counted, not guessed. The bar is indeterminate on purpose: the server reports no phase, and a bar\n that filled would be inventing progress.\n- **The two tracks are concurrent because they are.** The runner is `Promise.allSettled` over the probe and the crawl,\n so showing them as parallel is a fact, not a layout choice. Do not turn them into a sequence of phases.\n- **The no-script path must keep working.** The form still carries `method=\"post\" action=\"/check\"`, the enhancement\n falls back when the waiting view is absent, and a test asserts both.\n- **Reset Turnstile on failure.** A token is redeemed exactly once, and this page now survives a failed submit, so a\n retry without `turnstile.reset()` sends a spent token.\n- Motion is `transform` and `opacity` only, and stops entirely under `prefers-reduced-motion`.\n\n### Say it once\n\nThe page carried the same idea up to three times. It opened with a `DOMAIN REPORT` kicker over a derived display name\nover a subtitle naming the two tabs directly beneath it over the domain the name came from; then an `AI VISIBILITY`\nkicker repeating the active tab; then a sentence defining mention against cited, which the evidence section defined\nagain in its own words a screen later. All of it is named in `DESIGN.md` (\"Do not repeat a page choice through cards,\ntabs, and headings\") and in `PRODUCT.md`'s anti-references (\"Multiple headings that restate the same page\").\n\nSo: no section kickers. Six tiny uppercase labels over six headings is scaffolding, not voice, and the headings\nalready name their sections. The page title is the domain itself, because that is the subject and a derived name is\none more thing to read. Mention against cited is stated once, in the metric labels where the numbers are\n(`Mentioned in the answer`, `Cited as a source`), not in prose above them and again below.\n\nTone belongs in a whole frame and a glyph, never a coloured rail down one edge. A `border-left` heavier than 1px used\nas an accent is the side-stripe pattern; notices use a full tone-tinted border instead.\n\n### What is shared with `apps/web`, and what cannot be\n\nThe two surfaces must LOOK like one product, but they cannot SHARE code. `apps/web` is React 19 + Vite + Tailwind 4\nwith TanStack Query, and its components are bound to the generated SDK (`useQuery(getApiV1…Options({client:\nheyClient}))`). This Val is a Deno request handler that returns HTML strings, with no bundler and a `script-src 'self'`\npolicy. Importing a component would drag in the router, the query layer, and a Tailwind build.\n\nSo the design system is shared by VALUE, and the values must be copied exactly:\n\n- **Fonts.** Same package and version the dashboard bundles, `@fontsource-variable/geist@5.3.0` and `-mono`, loaded\n from jsDelivr because a Val cannot ship woff2 (binary files are rejected). Naming Geist in a font stack without\n loading it — which is what this page did originally — silently renders the whole surface in a system font.\n- **Typographic detail.** `font-feature-settings: \"cv11\", \"ss01\", \"ss03\"`, `-0.015em` heading tracking (`-0.02em` on\n h1), `\"ss02\", \"cv11\"` on monospace, and antialiasing. Without these the same typeface still reads as a different one.\n- **Colour.** Token values are copied from `apps/web/src/styles.css`, alpha included (`rgb(24 24 27 / 0.3)`), not\n eyeballed to a nearby hex. A test pins them.\n\nThe site map is the one place where sharing was considered and rejected. The dashboard solves its layout with\nForceAtlas2 + noverlap in a `node:worker_threads` worker and renders it with Sigma/WebGL, for graphs of 20k–50k nodes.\nVal Town has no worker threads, the page must render without JavaScript, and this graph is at most 24 nodes — a regime\nwhere a force simulation is both overkill and non-deterministic. The deterministic depth-ring layout is the right\ntool at this size, not a shortcut.\n\n## Architecture\n\n```mermaid\nflowchart LR\n B[Browser] --> H[Val Town Deno host]\n H --> V[\"@canonry/val-kit visibility core\"]\n H --> A[@canonry/aeo-audit]\n V --> G[Gemini: 1 plan + 3 queries]\n A --> C[5-page site sample]\n G --> S[Sanitized check result]\n C --> S\n S --> Q[Val-scoped SQLite]\n Q --> B\n Q --> M[MCP endpoint /mcp]\n K[canonry + aero skills] --> M\n M --> N[Any MCP client]\n```\n\nThe Deno host owns HTTP routes, the check runner's phases, quota policy, and HTML. Technical AEO comes from the pinned\naudit engine. The visibility contracts, bounded evidence runner, Gemini planner and adapter, the URL and Turnstile\nguards, and both stores come from the pinned kit; none of them read environment, storage, or HTTP state.\n\n```text\napps/vals/ai-visibility-check/\n├── main.http.tsx Val HTTP entry\n├── deno.json PUSHED production graph: Deno tasks and lint policy\n├── deno.lock Production dependency lock (public npm)\n├── deno.dev.json Local dev graph: links @canonry/val-kit from the workspace\n├── deno.dev.lock Dev dependency lock (linked kit)\n├── .vt/state.json Val and branch identity (gitignored; CI generates it from the deploy workflow)\n├── src/\n│ ├── app/ HTTP routes and response policy\n│ ├── jobs/ Request-bound check runner: phases, budget, sanitizers, visitor copy\n│ ├── mcp/ This Val's MCP server and tool surface\n│ ├── site-health/ Technical AEO adapter, link-graph sample, factor ordering\n│ └── ui/ View models, HTML, and browser script\n└── test/ Deno backend and UI tests, plus the local dev server\n```\n\nEverything the tree no longer lists — `visibility/`, `security/`, `storage/`, check-record identity and the lease\nmachinery, MCP framing, the generated skills, and the design tokens — is `@canonry/val-kit`, imported by subpath.\n\n## Dependencies\n\nEvery dependency is fully qualified at the import site (`npm:hono@4.12.25`, `npm:@canonry/val-kit@0.1.0/jobs`,\n`https://esm.town/v/std/sqlite/main.ts`). Val Town resolves the module graph from esm.town and does NOT apply a pushed\n`deno.json` import map, so a bare specifier deploys and then throws `not a dependency and not in import map` at the\nfirst request. `deno.json` therefore excludes the `no-import-prefix` lint rule, which exists to enforce the opposite\nconvention.\n\n### Two configs, because the kit is resolved from two different places\n\n`deno.json` is PUSHED. It is the production graph, and it must describe only what Val Town can see: the public\nregistry. A `links` entry there would point at a workspace no deployed val has, and a shared `lock` would be rewritten\nwith a resolution production cannot reproduce. So it carries no `links`, no `nodeModulesDir`, and no `lock` key, and\nthe contract test fails if one appears.\n\n`deno.dev.json` is LOCAL, and `.vtignore` keeps it (and `deno.dev.lock` and `node_modules/`) out of the push. It\nduplicates `compilerOptions`, `lint`, and `fmt` — Deno has no `extends`, so there is no way to share them — and adds\n`links: [\"../../../packages/val-kit\"]`, `nodeModulesDir: \"auto\"` (linking an npm package REQUIRES a node_modules\ndirectory; without it Deno refuses outright), and its own `lock: \"deno.dev.lock\"`. That is what lets one PR change the\nkit and this val together, before the kit is published. `deno.dev.lock` is committed, because `--frozen` needs it and\nCI checks out fresh.\n\n**Build the kit first.** Deno consumes an npm package as built JavaScript, and the kit's `exports` point at `dist/`,\nso `pnpm --filter @canonry/val-kit build` has to run before any Deno task here. The `check`, `test`, and `dev` tasks\nguard on `dist/index.js` and say so rather than failing inside a resolution error. Deno re-syncs its copy of a linked\npackage whenever that `dist/` changes, so rebuilding is the whole refresh step.\n\n## Fixed public limits\n\n- A visitor may supply up to three questions; the planner generates only the remainder, and is not called at all when\n all three are supplied. Supplied questions are IDENTITY, not tuning: they join `checkFingerprint`, so two callers\n asking different questions about one domain never share a cached result.\n- One grounded Gemini planning call creates the questions the visitor did not supply.\n- Three Gemini checks run with a concurrency limit of two.\n- The site sample checks at most five pages and 2,500 edges.\n- The full request stops after 45 seconds.\n- Turnstile, daily quotas, one active job, and a 24-hour cache bound public use.\n- The link map displays at most 24 nodes and 60 edges, and says so when it truncates.\n\nThe host scopes `allowPrivateHost` to the one host being crawled, per the boundary above. Failed provider\nchecks stay `Not measured` and do not reduce reported rates.\n\n## Local development\n\n```sh\ndeno task dev # http://localhost:8787 — stub runners, no network\nGEMINI_API_KEY=… deno task dev # real Gemini planner, probes, and crawl\n```\n\nIn-memory storage and no Turnstile, so the UI and `/mcp` both work without credentials. `npx\n@modelcontextprotocol/inspector` against `http://localhost:8787/mcp` drives the endpoint as a real client would.\n\n## Verification\n\nRun `pnpm --filter @canonry/val-kit build` from the repository root, then `deno task check`, `deno task lint`, and\n`deno task test` from this directory, plus `node scripts/sync-val-town-skills.mjs --check` from the root. Those three\ntasks validate the DEV graph, which is what CI's `vals` matrix job runs.\n\n`deno task check:prod` validates the PRODUCTION graph instead (plain `deno.json`, `--frozen`). It cannot pass until\nthe pinned kit version is on public npm — before that it fails with `npm package '@canonry/val-kit' does not exist` —\nwhich is the same gate the deploy workflow applies, on purpose. A deployment additionally requires a `vt push\n--dry-run` and a live health smoke test.\n\n## Production configuration\n\nSet in Val Town: `VAL_TOWN_ENV=production`, `GEMINI_API_KEY`, `CANONRY_QUOTA_SALT`, `TURNSTILE_SECRET_KEY`,\n`TURNSTILE_SITE_KEY`, `TURNSTILE_ALLOWED_HOSTNAMES`. Optional: `CANONRY_MCP_START_CHECKS=0` removes the MCP write\ntool; `CANONRY_MCP_PER_CLIENT_DAILY_LIMIT` sets its daily per-caller allowance (default 2).\n\nPublic checks are disabled when the production quota salt or Turnstile configuration is absent, so an unconfigured\ndeployment serves reads and skills but refuses to spend.\n\n## Release order\n\n1. Publish the pinned `@canonry/val-kit` version with the `Publish @canonry/val-kit` workflow\n (`.github/workflows/publish-val-kit.yml`). Until then the production graph cannot resolve, and both `check:prod`\n and the deploy workflow fail closed — by design, since a val that deploys against an unpublished pin throws at the\n first request instead of at the push.\n2. Refresh the production `deno.lock` with `deno check --allow-import main.http.tsx` (plain config, no `--frozen`) and\n commit it. `deno.dev.lock` is separate and is not touched by this.\n\n> **Deno blocks a freshly published version for 24 hours.** `deno check` applies a\n> minimum dependency age policy (default 24h) to reduce supply-chain risk, so the\n> step above fails with \"blocked by the minimum dependency age policy\" if the kit\n> was published minutes ago. Pass `--min-dep-age 0` to generate the lock anyway —\n> defensible for a first-party package this repo just built and published from a\n> reviewed commit. The override is only needed to CREATE the lock: once the lock\n> pins the version with its integrity hash, `--frozen` resolves from the lock and\n> the policy does not apply, so the deploy workflow needs no flag and no config.\n3. Regenerate the skill mirror with `node scripts/sync-val-town-skills.mjs`.\n4. Run the verification commands above, including `deno task check:prod`.\n5. Run `vt push --dry-run` and review the file plan. A local push reads `.vt/state.json`; CI has none, so the deploy\n workflow generates it from the val and branch IDs pinned in the workflow with\n `node scripts/write-val-town-state.mjs apps/vals/ai-visibility-check`.\n6. Run `vt push` only after approval.\n7. Request `/healthz` and confirm `{\"ok\":true}`.\n\n`vt push` makes the Val match this directory. It deletes remote-only files, so do not edit production in the Val Town\neditor.\n\n## A failed check says why\n\n`mentioned: null` / `cited: null` is a check that did not happen, and the row reads \"Not measured\". The runner already\nclassifies why into a closed set of safe strings (timed out, rate-limited, temporarily unavailable, credentials\nrejected, no answer text, unusable model, cancelled, generic), and `gemini-probe.ts` carries the message through.\n\nThe public sanitizer used to overwrite all of it with one \"This answer-engine check was unavailable.\". Nothing is\nlogged either, so the reason existed for one function call and was then destroyed: a row nobody, operator included,\ncould explain afterwards. `publicProbeError` now translates each known message into visitor wording (\"answer engine\",\nnot \"provider\") and falls back to the generic sentence for anything it does not recognize, so a sanitizer still never\ntrusts its input.\n\n`probe-error-copy.test.ts` drives the REAL runner into each failure, then asserts none of them lands on the generic\nfallback. That is the guard: a new failure mode added upstream without a translation fails the suite instead of\nsilently erasing its own reason. The banner leads with the reason only when every failed check shares one; with two\ndifferent reasons it would have to pick one and be wrong about the rest, so it defers to the per-row evidence.\n\n## Say it once, and say it where it belongs\n\nThe block under the landing form was three paragraphs of identical muted grey carrying five facts, two of them twice:\nthe question count sat in the hint and again in the page footer, and the single engine sat in its own sentence and\nagain in the footer. Repetition with no contrast is what made it read as a wall.\n\nIt is now two lines with two steps of hierarchy:\n\n- The **hint** (13px, `--secondary`) is an instruction and belongs to the questions field. `DESIGN.md` reserves\n `--muted` for nonessential metadata and forbids putting instructions in it, which is what the old block did with all\n three lines.\n- The **facts row** (12px, `--muted`, dot-separated) is scope metadata, so muted is correct there. It reuses the\n `.sample-facts` separator vocabulary, including the narrow-width collapse to a stack, since a wrapped item that\n begins with a separator reads as broken.\n\nThe footer sentence is gone from the LANDING, where the facts row above it already says everything, and kept on the\nRESULT page, where there is no form and a report read on its own must still state what it is a sample of. Both are\npinned by tests. The redundancy test counts on the visible block only: the tooltip's copy is deliberately written\ntwice, once as the trigger's accessible name and once as the body, which is one statement for two audiences.\n\n## The heading's tooltip is CSS only\n\nThe landing explains itself through a note on the heading rather than a subtitle. It opens on `:hover` and, critically,\n`:focus-within` — the page CSP allows no inline script, and the trigger must work before the enhancement script loads\nor without it at all. That is why the trigger is a real `${\n escapeHtml(copy)\n }`\n}\n\nfunction renderCheckForm(model: CanonryDemoViewModel, variant: 'hero' | 'compact' = 'compact'): string {\n if (!model.form) return ''\n const value = model.status === 'demo' || model.status === 'empty' ? '' : model.domain\n const verificationStatus = model.form.verificationStatus ?? (model.form.turnstileSiteKey ? 'ready' : 'not-required')\n const hasTurnstile = Boolean(model.form.turnstileSiteKey && verificationStatus === 'ready')\n const disabled = verificationStatus === 'unavailable'\n // interaction-only: the challenge still runs on load, so a token is ready at\n // submit, but the widget is drawn only if the visitor has to do something.\n // The default (`always`) meant the result page carried a green \"Success!\"\n // panel next to the check-another-domain form, announcing the outcome of a\n // challenge for a submission that had not happened, beside a report that had.\n const verification = hasTurnstile\n ? `

`\n : verificationStatus === 'unavailable'\n ? `

!${\n escapeHtml(\n model.form.verificationUnavailableMessage ?? 'Human verification is unavailable. Public checks are disabled.',\n )\n }

`\n : ''\n const verificationSlot = verification\n ? `

${verification}

`\n : ''\n const hero = variant === 'hero'\n return `\n

\n \n

\n \n \n

\n ${\n hero\n ? `

\n Questions you want to show up for optional\n \n

Add up to ${MAX_USER_QUERIES}. We generate the rest. ${QUERY_HINT_SUFFIX}

`\n : ''\n }\n ${\n hero\n // Scope facts, one line, said once. They used to be a sentence here and\n // a second sentence in the footer, which repeated the engine and the\n // question count the hint above already states.\n ? `

Gemini only5-page technical SEO auditMore engines in open source Canonry

`\n : ''\n }\n \n ${verificationSlot}\n

`\n}\n\nfunction renderMain(model: CanonryDemoViewModel): string {\n const glyphHref = assetUrl(DEFAULT_GLYPH_SRC, canonryGlyph)\n const globalNotice =\n (model.status === 'demo' || model.status === 'ready' ? model.notice : model.notice ?? statusCopy(model.status)) ??\n undefined\n const loading = model.status === 'loading'\n const visibility = model.visibility\n // Nothing has been checked yet, so a report header, tabs, and two empty\n // panels are scaffolding around an absence. Lead with the one action instead.\n if (model.status === 'empty') {\n return `\n

\n \n

Does AI mention your brand?${renderInfoTip(LANDING_EXPLAINER)}

\n ${renderCheckForm(model, 'hero')}\n

\n ${renderLoadingView()}\n

\n \n

`\n }\n return `\n

\n \n

${escapeHtml(model.domain)}

\n ${model.locale ? `

${escapeHtml(model.locale)}

` : ''}\n

\n ${model.status === 'demo' ? 'Sample data' : ''}\n

\n ${renderNotice(globalNotice)}\n

\n \n \n

\n ${\n visibility\n ? `${renderVisibilityChart(visibility)}${renderShareSection(visibility)}${renderEvidence(visibility)}`\n : '

No visibility result

Start a check to inspect answer-engine evidence.

'\n }\n

\n \n \n \n

`\n}\n\n/** Returns a complete document so the runtime can use it as an HTTP response body. */\nexport function renderCanonryDemo(model: CanonryDemoViewModel): string {\n const title = `${model.displayName} | AI Visibility Check`\n return `\n\n \n \n \n \n ${escapeHtml(title)}\n \n \n \n \n \n \n ${\n model.form?.turnstileSiteKey && (model.form.verificationStatus ?? 'ready') === 'ready'\n ? ''\n : ''\n }\n \n ${renderMain(model)}\n`\n}\n\n/** Useful for a host that owns the outer document or wants an embedded fragment. */\nexport function renderCanonryDemoBody(model: CanonryDemoViewModel): string {\n return renderMain(model)\n}\n",[],[197,283,285],"555b38fe-64c9-4c6f-9734-139ff6dabb8a","mark.ts","5b89fa92-a667-11f1-a7f4-1607ee4eb77e",195,["D",1788318220417],"/**\n * The Canonry company marks, derived from `plugins/canonry/assets/logo-dark.svg`.\n *\n * Two forms, because a logo and a glyph do different jobs.\n *\n * `canonryMark` keeps the plate and is the favicon, where a mark needs its own\n * field. `canonryGlyph` is the same paths with the plate removed and the\n * viewBox cropped to the artwork: inside the plate the bird fills 58% of the\n * width, so at byline size it rendered as a speck, and the plate's warm #1C1413\n * fought this page's cool zinc surface. Cropping is a reframe, not a redraw;\n * the paths are untouched.\n *\n * The cream is the brand's own #FFFAED, and against zinc it is the one warm\n * thing on the page. That is the point: it is the only element here that is\n * Canonry rather than this tool.\n *\n * This is the company silhouette, not the red canary. The canary is the\n * dashboard app's mark; the two are deliberately different.\n */\nexport const canonryMark =\n ''\n\nexport const canonryGlyph =\n ''\n",[],[197,283,294],"c2395220-2522-418a-8914-3e5fb0bc1ff5","index.ts","93608ea0-a63e-11f1-9b04-1607ee4eb77e",295,["D",1788465273985],9,"export { createPublicCheckForm } from './check-form.ts'\nexport { canonryDemoClientScript, QUERY_HINT_SUFFIX } from './client.ts'\nexport { emptyLandingViewModel, toCanonryDemoViewModel } from './from-check-record.ts'\nexport type { CheckRecordViewOptions } from './from-check-record.ts'\nexport { assetUrl, renderCanonryDemo, renderCanonryDemoBody } from './render.ts'\nexport { canonryDemoStyles, canonryGlyph, canonryMark } from 'npm:@canonry/val-kit@0.1.0/ui'\nexport type {\n CanonryDemoViewModel,\n CheckFormViewModel,\n DemoUiStatus,\n EvidenceSource,\n EvidenceState,\n ProviderDescriptor,\n QueryEvidenceViewModel,\n ShareEntryViewModel,\n ShareTailViewModel,\n ShareViewModel,\n SiteHealthDefectViewModel,\n SiteHealthFactorState,\n SiteHealthFactorViewModel,\n SiteHealthPageViewModel,\n SiteHealthProvenanceViewModel,\n SiteHealthViewModel,\n SiteMapEdgeViewModel,\n SiteMapNodeViewModel,\n SiteMapViewModel,\n UiAction,\n UiNotice,\n VisibilityMetric,\n VisibilitySummaryMetric,\n VisibilityViewModel,\n} from './types.ts'\n",[],[197,283,302],"fceae953-9091-454b-a4c1-392d4cba871f","from-check-record.ts","9329ca82-a63e-11f1-9b04-1607ee4eb77e",294,["D",1788465273744],13,"import {\n type CheckRecord,\n PUBLIC_CHECK_UNAVAILABLE,\n PUBLIC_RATE_LIMITED_ERROR_CODE,\n} from 'npm:@canonry/val-kit@0.1.0/jobs'\nimport {\n computeMentionShare,\n computeShareOfVoice,\n type ShareOfVoice,\n type VisibilityEvidence,\n type VisibilityReport,\n} from 'npm:@canonry/val-kit@0.1.0/visibility'\nimport type { CheckResult } from '../runtime/check-result.ts'\nimport { orderFactors } from '../site-health/factor-order.ts'\nimport type { SiteHealthPageSample, SiteHealthSample } from '../site-health/types.ts'\nimport type {\n CanonryDemoViewModel,\n CheckFormViewModel,\n QueryEvidenceViewModel,\n SiteHealthDefectViewModel,\n SiteHealthFactorViewModel,\n SiteHealthPageViewModel,\n VisibilityViewModel,\n} from './types.ts'\n\nexport interface CheckRecordViewOptions {\n form?: CheckFormViewModel\n displayName?: string\n locale?: string\n title?: string\n}\n\nconst LOCAL_READY_FORM: CheckFormViewModel = {\n action: '/check',\n method: 'post',\n verificationFieldName: 'cf-turnstile-response',\n verificationStatus: 'not-required',\n submitLabel: 'Check a domain',\n}\n\n/**\n * Converts a sanitized, durable public-check record into the narrow UI model.\n * It deliberately never turns an absent provider report into a 0% score.\n */\nexport function toCanonryDemoViewModel(\n record: CheckRecord | null,\n options: CheckRecordViewOptions = {},\n): CanonryDemoViewModel {\n const domain = record?.domain ?? ''\n const result = record?.result ?? null\n const status = record ? mapStatus(record) : 'empty'\n const resultDomain = result?.domain || domain\n const displayName = options.displayName ?? nameFromDomain(resultDomain || 'Canonry')\n const visibility = result?.visibility ? mapVisibility(result.visibility) : undefined\n const siteHealth = result?.siteHealth ? mapSiteHealth(result.siteHealth, result.generatedAt) : undefined\n\n return {\n status,\n title: options.title,\n displayName,\n domain: resultDomain,\n locale: options.locale,\n form: { ...LOCAL_READY_FORM, ...options.form },\n visibility,\n siteHealth,\n notice: buildNotice(record, result),\n }\n}\n\n/**\n * Did anything in this check actually fail?\n *\n * `record.status` is decided once, when the check runs, and stored. That makes\n * it the wrong thing to warn a reader off: when the rule behind it is corrected\n * the stored value stays wrong for the record's whole 24h life, and a reader\n * opening a shared link sees the old verdict forever. Every check written\n * before the bounded-sample rule was fixed still says `partial` with zero\n * failed probes and a completed crawl.\n *\n * The evidence is right here in the result, so read it instead of the flag: a\n * probe that failed, a crawl that errored, or a recorded phase error. Nothing\n * failed means no caution, whatever the stored status says.\n */\nfunction hasFailedWork(record: CheckRecord): boolean {\n const result = record.result\n if (!result) return false\n if (result.errors && result.errors.length > 0) return true\n if (result.siteHealth && result.siteHealth.status === 'error') return true\n return (result.visibility?.evidence ?? []).some((row) => row.mentioned === null && row.cited === null)\n}\n\nfunction mapStatus(record: CheckRecord): CanonryDemoViewModel['status'] {\n if (record.errorCode === PUBLIC_RATE_LIMITED_ERROR_CODE) return 'rate-limited'\n switch (record.status) {\n case 'queued':\n case 'running':\n return 'loading'\n case 'partial':\n // A stored `partial` is only worth a caution when something in the\n // result actually failed. See `hasFailedWork`.\n return hasFailedWork(record) ? 'partial' : 'ready'\n case 'failed':\n return 'error'\n case 'complete':\n return 'ready'\n }\n}\n\n/**\n * Percentages are rounded for display only. The shares they come from sum to\n * exactly 1; rounding each independently can land the printed column on 99 or\n * 101, so the bar is drawn from the unrounded share and only the labels round.\n */\nfunction mapShare(report: VisibilityReport): VisibilityViewModel['share'] {\n return toShareView(computeShareOfVoice(report.evidence, report.domain), report.domain)\n}\n\n/**\n * The mention table is keyed by NAME, so the target's row is labelled with the\n * brand the answers actually wrote when they named it, falling back to the\n * domain when no answer named it at all. Labelling that row with the domain\n * would put a domain in a table of names.\n */\nfunction mapMentionShare(report: VisibilityReport): VisibilityViewModel['mentionShare'] {\n const label = targetBrandLabel(report)\n return toShareView(computeMentionShare(report.evidence, label), label)\n}\n\nfunction targetBrandLabel(report: VisibilityReport): string {\n for (const row of report.evidence) {\n // matchedTerms holds the approved aliases this answer actually wrote. The\n // domain can appear there too, and a domain is not the brand's name.\n const name = row.matchedTerms.find((term) => !term.includes('.'))\n if (name) return name\n }\n return report.domain\n}\n\nfunction toShareView(share: ShareOfVoice | null, targetLabel: string): VisibilityViewModel['share'] {\n if (!share) return undefined\n return {\n basis: share.basis,\n measuredAnswers: share.measuredAnswers,\n totalAppearances: share.totalAppearances,\n unattributedAnswers: share.unattributedAnswers,\n targetDomain: targetLabel,\n targetPercent: Math.round((share.targetShare ?? 0) * 100),\n tail: share.tail ? { domains: share.tail.domains, percent: Math.round(share.tail.share * 100) } : null,\n entries: share.entries.map((entry) => ({\n domain: entry.domain,\n answers: entry.answers,\n percent: Math.round(entry.share * 100),\n isTarget: entry.isTarget,\n })),\n }\n}\n\nfunction mapVisibility(report: VisibilityReport): VisibilityViewModel {\n const providers = uniqueProviders(report.evidence)\n const denominator = report.summary.successfulChecks\n const mentioned = report.evidence.filter((row) => row.mentioned).length\n const cited = report.evidence.filter((row) => row.cited).length\n const failed = report.summary.failedChecks\n return {\n historyKind: 'snapshot',\n share: mapShare(report),\n mentionShare: mapMentionShare(report),\n requestedAt: report.startedAt,\n checkedAt: report.completedAt,\n providers,\n summaries: {\n mentioned: {\n rate: percent(report.summary.mentionRate),\n numerator: mentioned,\n denominator,\n },\n cited: {\n rate: percent(report.summary.citationRate),\n numerator: cited,\n denominator,\n },\n },\n completedChecks: denominator,\n requestedChecks: denominator + failed,\n failedChecks: failed,\n evidence: report.evidence.map(mapEvidence),\n notice: failed > 0\n ? {\n tone: 'caution',\n title: `${failed} ${failed === 1 ? 'check' : 'checks'} unavailable`,\n // The reason leads, because that is what a row reading \"Not measured\"\n // makes someone ask. It is only stated when the failures agree on one;\n // with several reasons the banner would have to pick one and be wrong\n // about the rest, so it defers to the per-row evidence instead.\n detail: `${failureReason(report.evidence) ?? ''}Mention and citation rates use completed checks only.`,\n }\n : undefined,\n }\n}\n\n/** The one reason every failed check shares, or null when they disagree. */\nfunction failureReason(evidence: readonly VisibilityEvidence[]): string | null {\n const reasons = new Set(\n evidence.filter((row) => row.mentioned === null && row.cited === null)\n .map((row) => row.error)\n // The generic sentence is the absence of a reason, and every check stored\n // before the sanitizer kept one carries it. Leading with it produces\n // \"1 check unavailable. This answer-engine check was unavailable.\"\n .filter((error): error is string => Boolean(error) && error !== PUBLIC_CHECK_UNAVAILABLE),\n )\n if (reasons.size !== 1) return null\n const [reason] = [...reasons]\n return reason ? `${reason} ` : null\n}\n\nfunction uniqueProviders(evidence: readonly VisibilityEvidence[]): VisibilityViewModel['providers'] {\n const seen = new Map()\n for (const row of evidence) {\n if (seen.has(row.provider)) continue\n seen.set(row.provider, {\n id: row.provider,\n label: providerLabel(row.provider),\n model: row.requestedModel ?? undefined,\n })\n }\n return [...seen.values()]\n}\n\nfunction mapEvidence(row: VisibilityEvidence): QueryEvidenceViewModel {\n // The portable probe distinguishes all provider sources from the sources\n // whose URL actually matches the target. Accept the old runtime shape while\n // it rolls forward, but never mark every cited source as a target citation.\n const matchedCitationUrls = new Set(readMatchedCitationUrls(row))\n return {\n id: `${row.provider}:${row.query}:${row.completedAt}`,\n query: row.query,\n provider: row.provider,\n providerLabel: providerLabel(row.provider),\n requestedModel: row.requestedModel,\n servedModel: row.servedModel,\n completedAt: row.completedAt,\n mentioned: row.mentioned,\n cited: row.cited,\n matchedTerms: row.matchedTerms,\n answerText: row.answerText,\n sources: row.sources.map((source) => ({\n url: source.url,\n title: source.title,\n isTargetDomain: matchedCitationUrls.has(source.url),\n })),\n searchQueries: row.searchQueries,\n retrievalStatus: mapRetrievalStatus(row.retrievalStatus),\n error: row.error,\n }\n}\n\nfunction readMatchedCitationUrls(row: VisibilityEvidence): readonly string[] {\n return (row as VisibilityEvidence & { matchedCitationUrls?: readonly string[] }).matchedCitationUrls ?? []\n}\n\nfunction percent(value: number | null): number | null {\n if (value == null || !Number.isFinite(value)) return null\n return Math.max(0, Math.min(100, value * 100))\n}\n\nfunction mapRetrievalStatus(status: VisibilityEvidence['retrievalStatus']): QueryEvidenceViewModel['retrievalStatus'] {\n if (status === 'error') return 'failed'\n if (status === 'grounded') return 'success'\n if (status === 'not-grounded') return 'not-measured'\n return 'pending'\n}\n\nfunction mapSiteHealth(sample: SiteHealthSample, checkedAt: string): NonNullable {\n const complete = sample.pages.filter((page) => page.status === 'success').length\n const failed = sample.pages.filter((page) => page.status === 'error').length\n const attempted = Math.min(5, Math.max(sample.pages.length, sample.pagesObserved))\n return {\n sampleLabel: sample.label,\n score: sample.score,\n discoveredPages: sample.pagesDiscovered,\n attemptedPages: attempted,\n completedPages: complete,\n failedPages: failed,\n checkedAt,\n // Best score first. Alphabetical order reads as a list of names; ranked\n // order reads as a result, with the work to do gathered at the bottom.\n factors: orderFactors(\n sample.factors.map((factor) => {\n const state = factorState(sample, factor.id, factor.count)\n const evidence = factorEvidence(sample, factor.id)\n return {\n id: factor.id,\n label: factor.name,\n state,\n score: state === 'measured' ? factor.averageScore : null,\n findings: evidence.findings,\n recommendations: evidence.recommendations,\n detail: state === 'measured'\n ? `Measured across ${factor.count} sampled ${factor.count === 1 ? 'page' : 'pages'}.`\n : state === 'not-applicable'\n ? 'Not applicable to the sampled page types.'\n : 'Not measured in this sample.',\n }\n }),\n (factor) => ({ score: factor.score, label: factor.label }),\n ),\n criticalDefects: criticalDefects(sample),\n worstPages: sample.pages.map(mapSiteHealthPage),\n // Passed through as measured. A crawl with no usable graph stays absent\n // rather than becoming an empty diagram that implies a site with no links.\n siteMap: sample.siteMap && sample.siteMap.nodes.length > 0\n ? {\n nodes: sample.siteMap.nodes,\n edges: sample.siteMap.edges,\n totalPages: sample.siteMap.totalPages,\n totalEdges: sample.siteMap.totalEdges,\n truncated: sample.siteMap.truncated,\n }\n : undefined,\n terminationReason: sample.terminationReason,\n provenance: {\n schemaVersion: sample.schemaVersion,\n rootUrl: sample.rootUrl,\n finalRootUrl: sample.finalRootUrl,\n attemptedHosts: sample.attemptedHosts,\n engineVersion: readOptionalString(sample, 'engineVersion') ?? readOptionalString(sample, 'crawlEngineVersion'),\n },\n notice: sample.status === 'error' || sample.error\n ? {\n tone: 'caution',\n title: 'Site sample unavailable',\n detail: sample.error ?? 'The Technical AEO sample could not complete.',\n }\n // Same rule as the top-level caution: warn about pages that FAILED, not\n // about a stored status. A crawl that stopped at its own page cap is the\n // sample working, and `sample.status` is frozen at check time so a\n // corrected rule never reaches a record already written.\n : failed > 0\n ? {\n tone: 'caution',\n title: 'Partial site sample',\n detail: `${failed} of ${attempted} sampled ${attempted === 1 ? 'page' : 'pages'} could not be audited. ` +\n 'Only completed pages contribute to the shown evidence.',\n }\n : sample.warnings.length\n ? { tone: 'caution', title: 'Sample warning', detail: sample.warnings[0]! }\n : undefined,\n }\n}\n\nfunction factorState(sample: SiteHealthSample, factorId: string, count: number): SiteHealthFactorViewModel['state'] {\n if (count > 0) return 'measured'\n const sampled = sample.pages.flatMap((page) => page.factors.filter((factor) => factor.id === factorId))\n if (sampled.length > 0 && sampled.every((factor) => factor.applicable === false)) return 'not-applicable'\n return 'unavailable'\n}\n\nfunction readOptionalString(value: object, key: string): string | null {\n const candidate = (value as Record)[key]\n return typeof candidate === 'string' && candidate.trim() ? candidate.trim() : null\n}\n\nfunction mapSiteHealthPage(page: SiteHealthPageSample): SiteHealthPageViewModel {\n const findings = [\n ...page.criticalDefects.map((defect) => defect.detail),\n ...page.factors.flatMap((factor) => factor.findings.map((finding) => finding.message)),\n ...(page.error ? [page.error] : []),\n ].filter(Boolean).slice(0, 6)\n return {\n url: page.url,\n score: page.score,\n status: page.status === 'error' ? 'unavailable' : (page.score ?? 0) >= 80 ? 'good' : 'needs-attention',\n findings,\n indexable: indexability(page.indexability),\n }\n}\n\n/**\n * Findings and fixes belong to the factor they came from.\n *\n * They used to be flattened into one \"Top fixes\" column beside a \"Factors\"\n * column, which separated a problem from its cause and printed the factor name\n * as the fix's own subtitle: the two columns restated each other. Aggregating\n * per factor, the way the dashboard's page audit does, means one row carries\n * the name, the score, the evidence, and what to do about it.\n *\n * Deduped across sampled pages because five pages of one template produce five\n * copies of the same sentence, and a list of five identical fixes reads as five\n * problems.\n */\nfunction factorEvidence(sample: SiteHealthSample, factorId: string): {\n findings: string[]\n recommendations: string[]\n} {\n const findings = new Set()\n const recommendations = new Set()\n for (const page of sample.pages) {\n for (const factor of page.factors) {\n if (factor.id !== factorId) continue\n for (const finding of factor.findings) if (finding.message) findings.add(finding.message)\n for (const recommendation of factor.recommendations) if (recommendation) recommendations.add(recommendation)\n }\n }\n return { findings: [...findings], recommendations: [...recommendations] }\n}\n\n/**\n * Defects sit outside the score, so they stay visible rather than collapsing\n * behind a disclosure with everything else.\n */\nfunction criticalDefects(sample: SiteHealthSample): SiteHealthDefectViewModel[] {\n const byKey = new Map()\n for (const page of sample.pages) {\n for (const defect of page.criticalDefects) {\n const key = `${defect.id}:${defect.detail}`\n const existing = byKey.get(key)\n if (existing) existing.pages += 1\n else {\n byKey.set(key, {\n id: defect.id,\n severity: defect.severity,\n detail: defect.detail,\n recommendation: defect.recommendation,\n pages: 1,\n })\n }\n }\n }\n return [...byKey.values()]\n}\n\nfunction indexability(value: string | null): boolean | null {\n if (!value) return null\n if (value === 'eligible' || value === 'indexable') return true\n if (value === 'hidden' || value === 'failed' || value === 'not-indexable') return false\n return null\n}\n\nfunction providerLabel(provider: string): string {\n const known: Record = {\n gemini: 'Gemini',\n openai: 'OpenAI',\n claude: 'Claude',\n perplexity: 'Perplexity',\n }\n return known[provider] ?? (provider ? `${provider.slice(0, 1).toUpperCase()}${provider.slice(1)}` : 'Unknown engine')\n}\n\nfunction buildNotice(\n record: CheckRecord | null,\n result: CheckResult | null,\n): CanonryDemoViewModel['notice'] {\n if (!record) return undefined\n if (record.errorCode === PUBLIC_RATE_LIMITED_ERROR_CODE) {\n return {\n tone: 'caution',\n title: 'Check limit reached',\n detail: record.errorMessage ?? 'This public sample has reached its current limit. Try again later.',\n }\n }\n if (record.status === 'failed') {\n return {\n tone: 'negative',\n title: 'This check could not finish',\n detail: record.errorMessage ?? 'Try another public domain later.',\n }\n }\n if (result?.errors.length) {\n const first = result.errors[0]!\n return {\n tone: 'caution',\n title: first.area === 'visibility' ? 'Visibility was unavailable' : 'Site sample was unavailable',\n detail: first.message,\n }\n }\n return undefined\n}\n\nfunction nameFromDomain(domain: string): string {\n const host = domain.replace(/^www\\./i, '').split('.')[0] ?? domain\n return host\n .replace(/[-_]+/g, ' ')\n .replace(/\\b\\w/g, (letter) => letter.toUpperCase())\n}\n\n/**\n * The landing view, shown before anything has been checked.\n *\n * It carries no `visibility` and no `siteHealth` because nothing has been\n * measured yet. Earlier this page rendered a fixture — four answer engines,\n * a four-week trend, invented model identifiers — labelled only by a badge in\n * the header, well above the numbers it qualified. Anyone scrolling read\n * fabricated data as measurement, and it advertised three engines this tool\n * does not run. An empty state is the honest thing to show when the answer is\n * \"nothing yet\".\n */\nexport function emptyLandingViewModel(form: CheckFormViewModel): CanonryDemoViewModel {\n return {\n status: 'empty',\n title: 'AI Visibility Check',\n displayName: 'Check a domain',\n domain: '',\n form,\n }\n}\n",[],[197,283,311],"ebebf191-63d3-4bd5-a0da-c99bdac6307f","client.ts","933a30f2-a63e-11f1-aa2a-1607ee4eb77e",220,["D",1788362833780],"/**\n * The one place the timing is written. The script below rewrites the query\n * hint's text on every keystroke, so a suffix left only in the server markup\n * would survive until the visitor types and then silently disappear.\n */\nexport const QUERY_HINT_SUFFIX = 'Takes about 45 seconds.'\n\n/** Client-side enhancement only. The page remains usable with native forms and details. */\nexport const canonryDemoClientScript = `\n(() => {\n const tabs = Array.from(document.querySelectorAll('[data-report-tab]'));\n const panels = Array.from(document.querySelectorAll('[data-report-panel]'));\n const setTab = (name, focus) => {\n tabs.forEach((tab) => {\n const active = tab.dataset.reportTab === name;\n tab.setAttribute('aria-selected', String(active));\n tab.tabIndex = active ? 0 : -1;\n if (active && focus) tab.focus();\n });\n panels.forEach((panel) => { panel.hidden = panel.dataset.reportPanel !== name; });\n };\n tabs.forEach((tab, index) => {\n tab.addEventListener('click', () => setTab(tab.dataset.reportTab, false));\n tab.addEventListener('keydown', (event) => {\n if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return;\n event.preventDefault();\n const target = event.key === 'Home' ? 0 : event.key === 'End' ? tabs.length - 1 : (index + (event.key === 'ArrowRight' ? 1 : tabs.length - 1)) % tabs.length;\n const next = tabs[target];\n if (next) setTab(next.dataset.reportTab, true);\n });\n });\n const queries = document.querySelector('[data-query-hint]');\n const queryInput = document.getElementById('queries-input');\n if (queries && queryInput) {\n const max = Number(queries.dataset.max || 3);\n const update = () => {\n const used = queryInput.value.split('\\\\n').map((line) => line.trim()).filter((line) => line.length >= 3).length;\n const kept = Math.min(used, max);\n const rest = max - kept;\n const counts = kept === 0\n ? 'Add up to ' + max + '. We generate the rest.'\n : rest === 0\n ? 'Using your ' + kept + '. We generate none.'\n : 'Using your ' + kept + '. We generate the other ' + rest + '.';\n // Interpolated at module load so the server markup and every rewrite of\n // this line read one constant.\n queries.textContent = counts + ' ' + ${JSON.stringify(QUERY_HINT_SUFFIX)};\n };\n queryInput.addEventListener('input', update);\n update();\n }\n\n const form = document.querySelector('[data-domain-check-form]');\n if (form) {\n const submit = form.querySelector('[data-domain-submit]');\n const busy = form.querySelector('[data-form-busy]');\n const checking = document.querySelector('[data-checking]');\n\n const markBusy = () => {\n form.setAttribute('aria-busy', 'true');\n if (submit instanceof HTMLButtonElement) {\n submit.disabled = true;\n submit.setAttribute('aria-disabled', 'true');\n submit.textContent = 'Starting…';\n }\n if (busy) {\n busy.hidden = false;\n busy.classList.remove('is-error');\n busy.textContent = 'Starting check…';\n }\n };\n\n // Without the waiting view there is nothing to enhance: fall back to the\n // native POST, which still works, just with a blocked browser.\n if (!checking) {\n form.addEventListener('submit', markBusy);\n } else {\n const elapsedEl = checking.querySelector('[data-checking-elapsed]');\n const domainEl = checking.querySelector('[data-checking-domain]');\n const queriesEl = checking.querySelector('[data-checking-queries]');\n const hero = document.querySelector('[data-hero]');\n\n const restore = (message) => {\n checking.hidden = true;\n if (hero) hero.hidden = false;\n form.removeAttribute('aria-busy');\n if (submit instanceof HTMLButtonElement) {\n submit.disabled = false;\n submit.removeAttribute('aria-disabled');\n submit.textContent = submit.dataset.label || 'Check a domain';\n }\n if (busy) {\n busy.hidden = false;\n // A failure and \"Starting check…\" used to be the same 13px grey line,\n // sitting under two more 13px grey lines. Hiding the waiting view and\n // restoring the hero then read as the page bouncing back to the form\n // with no explanation, when the explanation was right there.\n busy.classList.add('is-error');\n busy.textContent = message;\n }\n // A Turnstile token is redeemed exactly once. The page is still here\n // after a failure, so the spent token has to be replaced before the\n // visitor can try again.\n if (window.turnstile && typeof window.turnstile.reset === 'function') {\n try { window.turnstile.reset(); } catch (_) { /* widget absent */ }\n }\n };\n\n form.addEventListener('submit', (event) => {\n const data = new FormData(form);\n const domain = String(data.get('domain') || '').trim();\n if (!domain) return;\n event.preventDefault();\n markBusy();\n\n if (domainEl) domainEl.textContent = domain;\n const typed = String(data.get('queries') || '')\n .split('\\\\n').map((line) => line.trim()).filter((line) => line.length >= 3).slice(0, 3);\n if (queriesEl) {\n queriesEl.textContent = '';\n for (const question of typed) {\n const item = document.createElement('li');\n item.textContent = question;\n queriesEl.appendChild(item);\n }\n queriesEl.hidden = typed.length === 0;\n }\n if (hero) hero.hidden = true;\n checking.hidden = false;\n\n const started = Date.now();\n const tick = setInterval(() => {\n if (elapsedEl) elapsedEl.textContent = Math.round((Date.now() - started) / 1000) + 's';\n }, 1000);\n\n fetch(form.dataset.jsonAction || '/api/checks', {\n method: 'POST',\n headers: { 'content-type': 'application/json', accept: 'application/json' },\n body: JSON.stringify({\n domain: domain,\n queries: typed,\n turnstileToken: data.get('cf-turnstile-response') || null,\n }),\n })\n .then((response) => response.json().then((body) => ({ ok: response.ok, body: body })))\n .then((result) => {\n clearInterval(tick);\n const id = result.body && result.body.check && result.body.check.id;\n if (result.ok && id) {\n location.href = '/?check=' + encodeURIComponent(id);\n return;\n }\n const error = result.body && result.body.error;\n restore((error && error.message) || 'The check could not be started. Try again.');\n })\n .catch(() => {\n clearInterval(tick);\n restore('The check could not be reached. Try again.');\n });\n });\n }\n }\n})();\n`\n",[],[197,283,320],"425097da-b3ab-4306-b192-10a553d4d7ee","check-form.ts","9316a416-a63e-11f1-8fd4-1607ee4eb77e",296,["D",1788465274047],"import type { ValTownConfig } from 'npm:@canonry/val-kit@0.1.0/config'\nimport type { CheckFormViewModel } from './types.ts'\n\ntype PublicCheckFormConfig = Pick<\n ValTownConfig,\n | 'publicChecksEnabled'\n | 'publicChecksUnavailableMessage'\n | 'humanVerificationStatus'\n | 'turnstileSiteKey'\n>\n\n/** Builds the public form from the complete admission capability, not CAPTCHA alone. */\nexport function createPublicCheckForm(config: PublicCheckFormConfig): CheckFormViewModel {\n const unavailable = !config.publicChecksEnabled\n return {\n action: '/check',\n method: 'post',\n verificationFieldName: 'cf-turnstile-response',\n turnstileSiteKey: unavailable ? null : config.turnstileSiteKey,\n turnstileAction: 'audit',\n verificationStatus: unavailable ? 'unavailable' : config.humanVerificationStatus,\n verificationUnavailableMessage: unavailable\n ? config.publicChecksUnavailableMessage ?? 'Public checks are temporarily unavailable.'\n : 'Human verification is not configured. Public checks are disabled.',\n submitLabel: 'Check a domain',\n }\n}\n",[],[197,283,328],"860a6741-04fd-4cac-81b8-88fa850c061e",["D",1788292309086],[236,237,238,239,240,241,242],[197,283],"557649bd-7156-4137-9af2-6a32e284decc","memory.ts","95930b94-a63e-11f1-93d2-1607ee4eb77e","927bf83a-a63e-11f1-8d00-1607ee4eb77e",60,["D",1788292315183],"import type { CheckAdmission, CheckAdmissionInput, CheckRecord, CheckStore } from '../runtime/types.ts'\n\nconst ADMISSION_LEASE_PREFIX = 'public-check-admission:'\nconst ADMISSION_LEASE_MS = 10_000\nconst ADMISSION_RETRIES = 8\nconst ADMISSION_RETRY_DELAY_MS = 8\n\n/** Deterministic store for local development and tests. Production uses Val SQLite. */\nexport class MemoryCheckStore implements CheckStore {\n readonly checks = new Map()\n readonly quota = new Map()\n\n initialize(): Promise {\n return Promise.resolve()\n }\n\n async admit(input: CheckAdmissionInput): Promise {\n const leaseName = `${ADMISSION_LEASE_PREFIX}${input.candidate.fingerprint}`\n const leaseUntil = new Date(new Date(input.now).getTime() + ADMISSION_LEASE_MS).toISOString()\n\n for (let attempt = 0; attempt < ADMISSION_RETRIES; attempt++) {\n const holder = crypto.randomUUID()\n if (!await this.claimGlobalLease(leaseName, holder, input.now, leaseUntil)) {\n if (attempt + 1 < ADMISSION_RETRIES) await delay(ADMISSION_RETRY_DELAY_MS)\n continue\n }\n\n try {\n const reusable = await this.findReusable(input.candidate.fingerprint, input.now)\n if (reusable) return { kind: 'reused', record: reusable }\n\n const stale = this.findStaleRunning(input.candidate.fingerprint, input.now)\n if (stale) {\n const current = this.checks.get(stale.id)\n if (current?.status === 'running' && (!current.leaseUntil || current.leaseUntil <= input.now)) {\n const reclaimed: CheckRecord = {\n ...current,\n status: 'queued',\n updatedAt: input.now,\n leaseOwner: null,\n leaseUntil: null,\n }\n this.checks.set(reclaimed.id, reclaimed)\n return { kind: 'reclaimed', record: clone(reclaimed) }\n }\n const retried = await this.findReusable(input.candidate.fingerprint, input.now)\n if (retried) return { kind: 'reused', record: retried }\n }\n\n if (\n !await this.claimQuota(\n input.clientQuota.scope,\n input.clientQuota.subject,\n input.clientQuota.day,\n input.clientQuota.max,\n )\n ) {\n return { kind: 'quota-exhausted', scope: 'client' }\n }\n if (\n !await this.claimQuota(\n input.globalQuota.scope,\n input.globalQuota.subject,\n input.globalQuota.day,\n input.globalQuota.max,\n )\n ) {\n this.releaseQuota(input.clientQuota.scope, input.clientQuota.subject, input.clientQuota.day)\n return { kind: 'quota-exhausted', scope: 'global' }\n }\n\n try {\n await this.create(input.candidate)\n return { kind: 'created', record: clone(input.candidate) }\n } catch (error) {\n this.releaseQuota(input.clientQuota.scope, input.clientQuota.subject, input.clientQuota.day)\n this.releaseQuota(input.globalQuota.scope, input.globalQuota.subject, input.globalQuota.day)\n throw error\n }\n } finally {\n await this.releaseGlobalLease(leaseName, holder)\n }\n }\n\n return { kind: 'busy' }\n }\n\n findReusable(fingerprint: string, now: string): Promise {\n const candidates = [...this.checks.values()]\n .filter((check) => check.fingerprint === fingerprint)\n .sort((a, b) => b.createdAt.localeCompare(a.createdAt))\n for (const check of candidates) {\n if (check.status === 'queued') return Promise.resolve(clone(check))\n if (check.status === 'running' && check.leaseUntil && check.leaseUntil > now) return Promise.resolve(clone(check))\n if ((check.status === 'complete' || check.status === 'partial') && check.expiresAt && check.expiresAt > now) {\n return Promise.resolve(clone(check))\n }\n }\n return Promise.resolve(null)\n }\n\n create(record: CheckRecord): Promise {\n this.checks.set(record.id, clone(record))\n return Promise.resolve()\n }\n\n get(id: string): Promise {\n const record = this.checks.get(id)\n return Promise.resolve(record ? clone(record) : null)\n }\n\n update(\n id: string,\n patch: Partial>,\n ): Promise {\n const current = this.checks.get(id)\n if (!current) return Promise.resolve(null)\n const next = { ...current, ...clone(patch) }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n claimJob(id: string, owner: string, now: string, leaseUntil: string): Promise {\n const current = this.checks.get(id)\n if (!current) return Promise.resolve(null)\n const canClaim = current.status === 'queued' ||\n (current.status === 'running' && (!current.leaseUntil || current.leaseUntil <= now))\n if (!canClaim) return Promise.resolve(null)\n const next: CheckRecord = { ...current, status: 'running', updatedAt: now, leaseOwner: owner, leaseUntil }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n finalizeJob(\n id: string,\n owner: string,\n patch: Partial>,\n ): Promise {\n const current = this.checks.get(id)\n if (!current || current.leaseOwner !== owner) return Promise.resolve(null)\n const next: CheckRecord = { ...current, ...clone(patch), leaseOwner: null, leaseUntil: null }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n requeueJob(id: string, owner: string, now: string): Promise {\n const current = this.checks.get(id)\n if (!current || current.leaseOwner !== owner) return Promise.resolve(null)\n const next: CheckRecord = { ...current, status: 'queued', updatedAt: now, leaseOwner: null, leaseUntil: null }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n claimGlobalLease(name: string, holder: string, now: string, leaseUntil: string): Promise {\n const current = this.globalLeases.get(name)\n if (current && current.holder !== holder && current.leaseUntil > now) return Promise.resolve(false)\n this.globalLeases.set(name, { holder, leaseUntil })\n return Promise.resolve(true)\n }\n\n releaseGlobalLease(name: string, holder: string): Promise {\n if (this.globalLeases.get(name)?.holder === holder) this.globalLeases.delete(name)\n return Promise.resolve()\n }\n\n claimQuota(scope: string, subject: string, day: string, max: number): Promise {\n const key = `${scope}:${subject}:${day}`\n const value = this.quota.get(key) ?? 0\n if (value >= max) return Promise.resolve(false)\n this.quota.set(key, value + 1)\n return Promise.resolve(true)\n }\n\n private findStaleRunning(fingerprint: string, now: string): CheckRecord | null {\n const candidate = [...this.checks.values()]\n .filter((check) =>\n check.fingerprint === fingerprint && check.status === 'running' &&\n (!check.leaseUntil || check.leaseUntil <= now)\n )\n .sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0]\n return candidate ? clone(candidate) : null\n }\n\n private releaseQuota(scope: string, subject: string, day: string): void {\n const key = `${scope}:${subject}:${day}`\n const value = this.quota.get(key) ?? 0\n if (value <= 1) this.quota.delete(key)\n else this.quota.set(key, value - 1)\n }\n\n private readonly globalLeases = new Map()\n}\n\nfunction delay(ms: number): Promise {\n return new Promise((resolve) => setTimeout(resolve, ms))\n}\n\nfunction clone(value: T): T {\n return structuredClone(value)\n}\n",[],[197,348,340],"storage","01568ee8-b51f-43e3-8630-3492a546a4c6",["D",1788292310084],[234],[197,348],"91337973-d38e-4a6d-a2aa-3ee96855b5a1","4893fb98-a7d1-11f1-b89c-1607ee4eb77e","92bd6c2a-a63e-11f1-9f99-1607ee4eb77e",290,["D",1788465273055],"/**\n * The shape of this val's Technical AEO sample.\n *\n * It is a PRODUCT schema, not a kit contract: it names five pages, a link\n * graph, and a factor scorecard, none of which another val's check would\n * produce. `@canonry/val-kit` stores it opaquely as the `TResult` of a\n * `CheckRecord`, so what it contains is decided here and nowhere else — see\n * `../runtime/check-result.ts` for the record it hangs on, and bump\n * `CHECK_FINGERPRINT_NAMESPACE` when a change to these types adds or removes a\n * measured signal.\n */\n\nexport interface FactorSample {\n id: string\n name: string\n score: number\n applicable: boolean | null\n findings: Array<{ code: string; message: string }>\n recommendations: string[]\n}\n\nexport interface SiteHealthPageSample {\n url: string\n status: 'success' | 'error'\n score: number | null\n depth: number | null\n indexability: string | null\n factors: FactorSample[]\n criticalDefects: Array<{\n id: string\n severity: string\n detail: string\n recommendation: string\n }>\n error: string | null\n}\n\n/**\n * One page in the crawled link graph. A node is either a page the crawler\n * actually fetched and audited (`crawled`), or a link target it saw but never\n * opened — the distinction matters, because only a crawled node can carry a\n * score, and drawing the two alike would imply measurement that never happened.\n */\nexport interface SiteMapNode {\n key: string\n url: string\n /** Path for display, or the host for the site root. */\n label: string\n depth: number | null\n crawled: boolean\n score: number | null\n indexable: boolean | null\n inboundLinks: number\n outboundLinks: number\n}\n\n/** A followable-or-not internal link between two mapped nodes. */\nexport interface SiteMapEdge {\n from: string\n to: string\n followable: boolean\n}\n\n/**\n * A bounded internal-link graph built from the same crawl as the page audit.\n *\n * `totalPages` / `totalEdges` are the pre-cap totals, so a reader can always\n * tell a displayed sample from the whole site.\n */\nexport interface SiteMapSample {\n nodes: SiteMapNode[]\n edges: SiteMapEdge[]\n totalPages: number\n totalEdges: number\n truncated: boolean\n}\n\nexport interface SiteHealthSample {\n schemaVersion: string\n label: '5-page Technical AEO sample'\n domain: string\n rootUrl: string\n finalRootUrl: string | null\n status: 'complete' | 'partial' | 'error'\n score: number | null\n pagesDiscovered: number\n pagesFetched: number\n pagesObserved: number\n elapsedMs: number\n terminationReason: string | null\n warnings: string[]\n factors: Array<{ id: string; name: string; averageScore: number; count: number }>\n pages: SiteHealthPageSample[]\n /** Null when the crawl produced no usable graph, never an empty stand-in. */\n siteMap: SiteMapSample | null\n attemptedHosts: string[]\n error: string | null\n}\n\n/** The phase that produces the sample above. The kit never runs it. */\nexport interface SiteHealthRunner {\n run(domain: string, signal: AbortSignal): Promise\n}\n",[],[197,361,273],"site-health","8beab37b-a96d-48ee-be5f-d77198559def","site-map.ts","bf52f586-a641-11f1-bb98-1607ee4eb77e",289,["D",1788465273203],"/**\n * Build a bounded internal-link graph from a crawl the audit already ran.\n *\n * The crawler observes up to 2,500 edges while auditing five pages, and until\n * now every one of them was discarded. They are the most interesting thing in\n * the report for a reader: an audit score says a page is weak, the link graph\n * says whether anything points at it.\n *\n * Two node kinds, kept visibly distinct. A CRAWLED node was fetched and\n * audited, so it carries a score and an indexability verdict. A DISCOVERED node\n * is a link target the crawler saw but never opened; it has a URL and nothing\n * else. Rendering them alike would imply a measurement that never happened.\n *\n * Selection is deterministic — no clock, no randomness — so the same crawl\n * always produces the same picture, and a cached result never disagrees with\n * the run that produced it.\n */\nimport type { CrawlEdgeObservation, CrawlPageObservation } from 'npm:@canonry/aeo-audit@7.1.0'\nimport type { SiteMapEdge, SiteMapNode, SiteMapSample } from './types.ts'\n\n/**\n * Display caps, not crawl caps. Past roughly this many nodes a static graph\n * stops being readable and becomes decoration.\n */\nexport const SITE_MAP_MAX_NODES = 24\nexport const SITE_MAP_MAX_EDGES = 60\n\n/** Path for display, or the host for the site root. Query and hash are dropped. */\nfunction nodeLabel(url: string): string {\n try {\n const parsed = new URL(url)\n const path = parsed.pathname.replace(/\\/+$/, '')\n return path === '' ? parsed.hostname.replace(/^www\\./i, '') : path\n } catch {\n return url\n }\n}\n\nfunction indexableOf(page: CrawlPageObservation): boolean | null {\n const state = page.indexability?.state\n if (state === 'indexable') return true\n if (state === 'noindex' || state === 'blocked') return false\n return null\n}\n\n/**\n * A crawled page is keyed by the URL it settled on, because that is the URL its\n * inbound links resolve to. Keying by the requested URL would leave a redirected\n * page looking unlinked.\n */\nfunction pageKey(page: CrawlPageObservation): string {\n return page.finalUrl ?? page.requestedUrl\n}\n\nexport function buildSiteMap(\n pages: readonly CrawlPageObservation[],\n edges: readonly CrawlEdgeObservation[],\n): SiteMapSample | null {\n const internal = edges.filter((edge) => edge.classification === 'internal' && edge.from !== edge.to)\n if (pages.length === 0 && internal.length === 0) return null\n\n // Count one link per (from, to) pair. The engine keys edge observations by\n // (from, to, type), so a page that both anchor-links a target and points at it\n // via rel=canonical (or a redirect) emits several observations for one link;\n // tallying each would inflate the inbound/outbound counts the sampled-pages\n // table shows. `uniquePairs` is the deduped edge total, reused below.\n const inbound = new Map()\n const outbound = new Map()\n const uniquePairs = new Set()\n for (const edge of internal) {\n // A space cannot occur in a URL, so it is a safe (from, to) separator.\n const pair = `${edge.from} ${edge.to}`\n if (uniquePairs.has(pair)) continue\n uniquePairs.add(pair)\n outbound.set(edge.from, (outbound.get(edge.from) ?? 0) + 1)\n inbound.set(edge.to, (inbound.get(edge.to) ?? 0) + 1)\n }\n\n const crawled = new Map()\n for (const page of pages) crawled.set(pageKey(page), page)\n\n const candidates = new Set([...crawled.keys()])\n for (const edge of internal) {\n candidates.add(edge.from)\n candidates.add(edge.to)\n }\n\n const toNode = (url: string): SiteMapNode => {\n const page = crawled.get(url)\n return {\n key: url,\n url,\n label: nodeLabel(url),\n depth: page?.depth ?? null,\n crawled: page !== undefined,\n score: page?.audit?.overallScore ?? null,\n indexable: page ? indexableOf(page) : null,\n inboundLinks: inbound.get(url) ?? 0,\n outboundLinks: outbound.get(url) ?? 0,\n }\n }\n\n // Crawled pages are never dropped — they are what was actually measured.\n // Remaining slots go to the most-linked discovered targets, since a page\n // twelve others point at says more about the site than an orphan does.\n const all = [...candidates].map(toNode)\n const keptCrawled = all.filter((node) => node.crawled).sort(byDepthThenUrl)\n const discovered = all.filter((node) => !node.crawled).sort(byInboundThenUrl)\n const nodes = [...keptCrawled, ...discovered].slice(0, SITE_MAP_MAX_NODES)\n const nodeKeys = new Set(nodes.map((node) => node.key))\n\n const mapped: SiteMapEdge[] = internal\n .filter((edge) => nodeKeys.has(edge.from) && nodeKeys.has(edge.to))\n .map((edge) => ({ from: edge.from, to: edge.to, followable: edge.followableOccurrences > 0 }))\n const dedupedEdges = dedupe(mapped).sort(byEndpoints).slice(0, SITE_MAP_MAX_EDGES)\n\n return {\n nodes,\n edges: dedupedEdges,\n totalPages: candidates.size,\n totalEdges: uniquePairs.size,\n // Compare deduped-to-deduped. `internal.length` counts per-type observations,\n // so using it here reported \"showing N of N, truncated\" whenever a pair had\n // more than one edge type even though every unique edge was displayed.\n truncated: candidates.size > nodes.length || uniquePairs.size > dedupedEdges.length,\n }\n}\n\nfunction byDepthThenUrl(a: SiteMapNode, b: SiteMapNode): number {\n return (a.depth ?? 99) - (b.depth ?? 99) || a.url.localeCompare(b.url)\n}\n\nfunction byInboundThenUrl(a: SiteMapNode, b: SiteMapNode): number {\n return b.inboundLinks - a.inboundLinks || a.url.localeCompare(b.url)\n}\n\nfunction byEndpoints(a: SiteMapEdge, b: SiteMapEdge): number {\n return a.from.localeCompare(b.from) || a.to.localeCompare(b.to)\n}\n\n/** One edge per (from, to); the crawler already aggregates occurrences. */\nfunction dedupe(edges: readonly SiteMapEdge[]): SiteMapEdge[] {\n const seen = new Map()\n for (const edge of edges) {\n // Written as an escape, not a literal: a raw NUL byte makes the file\n // binary and Val Town refuses to push it. NUL is still the right\n // separator here, because it cannot occur in a URL.\n const key = `${edge.from}\\u0000${edge.to}`\n const existing = seen.get(key)\n if (existing) existing.followable ||= edge.followable\n else seen.set(key, { ...edge })\n }\n return [...seen.values()]\n}\n",[],[197,361,363],"b65ddacc-c7e0-4401-b401-bfac50edf5a0","runner.ts","96c08e88-a63e-11f1-8c22-1607ee4eb77e",264,["D",1788376306141],"import { runSiteCrawl } from 'npm:@canonry/aeo-audit@7.1.0'\nimport type { CrawlPageObservation, SiteCrawlOptions, SiteCrawlReport } from 'npm:@canonry/aeo-audit@7.1.0'\nimport { wwwAlternate } from '../security/url.ts'\nimport { buildSiteMap } from './site-map.ts'\nimport type { FactorSample, SiteHealthPageSample, SiteHealthRunner, SiteHealthSample } from '../runtime/types.ts'\n\nexport const VAL_TOWN_SITE_HEALTH_LIMITS = Object.freeze({\n mode: 'full' as const,\n maxPages: 5,\n maxEdges: 2_500,\n maxFetches: 32,\n maxDurationMs: 20_000,\n maxBytes: 12 * 1024 * 1024,\n maxPageBytes: 2 * 1024 * 1024,\n maxDepth: 2,\n maxLinksPerPage: 250,\n maxQueryVariants: 2,\n maxSitemapFanout: 8,\n maxSitemapUrls: 250,\n concurrency: 2,\n requestDelayMs: 100,\n respectRobots: true,\n checkDeadLinks: false,\n includeGeo: false,\n includeAgentSkills: false,\n includeLighthouse: false,\n}) satisfies SiteCrawlOptions\n\ntype Crawl = (rootUrl: string, options: SiteCrawlOptions) => Promise\n\nexport function createSiteHealthRunner(crawl: Crawl = runSiteCrawl): SiteHealthRunner {\n return {\n async run(domain, parentSignal) {\n const hosts = [domain, wwwAlternate(domain)].filter((value): value is string => Boolean(value))\n const attemptedHosts: string[] = []\n const signal = AbortSignal.any([parentSignal, AbortSignal.timeout(30_000)])\n let primaryError: unknown = null\n\n for (let index = 0; index < hosts.length; index++) {\n const host = hosts[index]!\n attemptedHosts.push(host)\n try {\n // `allowPrivateHost` names the ONE host being crawled, which is what\n // makes Technical AEO possible on Val Town at all.\n //\n // The engine's SSRF guard resolves every hostname with DNS and rejects\n // private addresses before opening a socket. Val Town grants no DNS:\n // `Deno.resolveDns` lacks net access to the resolver and\n // `node:dns.resolve4` returns UNKNOWN, so the guard failed closed on\n // every host and the crawl audited zero pages for every domain.\n //\n // This is not a way to switch the guard off; the option is a hostname,\n // not a boolean, precisely so it cannot be. A matching host skips the\n // DNS preflight and IP pinning (fetch-page.ts), and every OTHER host —\n // a redirect to cloud metadata, an internal service reached from a\n // sitemap — is still resolved and still blocked.\n //\n // `host` is safe to name because `normalizePublicDomain` has already\n // rejected localhost, .local, every private IPv4 range and all IPv6\n // literals before this runs. If it nonetheless rebinds to a private\n // address, Val Town's own sandbox refuses the fetch: 169.254.169.254,\n // 127.0.0.1, 10/8 and 192.168/16 all fail with \"Requires net access\"\n // before a socket opens.\n const report = await crawl(`https://${host}/`, {\n ...VAL_TOWN_SITE_HEALTH_LIMITS,\n allowPrivateHost: host,\n signal,\n })\n if (index === 0 && hosts[1] && shouldTryWwwAlternate(report, hosts[1])) continue\n return toSample(domain, report, attemptedHosts)\n } catch (error) {\n primaryError ??= error\n }\n }\n\n return failedSample(domain, attemptedHosts, safeError(primaryError))\n },\n }\n}\n\nfunction shouldTryWwwAlternate(report: SiteCrawlReport, alternateHost: string): boolean {\n if (report.summary.pagesFetched === 0 && report.summary.pagesObserved === 0) return true\n if (report.summary.terminationReason !== 'root-host-redirect' || !report.summary.finalRootUrl) return false\n try {\n return new URL(report.summary.finalRootUrl).hostname.toLowerCase().replace(/\\.$/, '') === alternateHost\n } catch {\n return false\n }\n}\n\nfunction toSample(domain: string, report: SiteCrawlReport, attemptedHosts: string[]): SiteHealthSample {\n const summary = report.summary\n const pages = report.mode === 'full' ? report.pages.map(toPage).sort(sortWorstFirst).slice(0, 5) : []\n // Built from the full observation set, not the worst-first five above: the\n // graph's value is the links between pages, and slicing first would sever them.\n const siteMap = report.mode === 'full' ? buildSiteMap(report.pages, report.edges) : null\n // v7 always reports this count. Treat a missing legacy/mock field as unknown\n // rather than inventing an error; an explicit zero is never a valid sample.\n const hasAuditedPages = summary.auditRollup.auditedPages !== 0\n const status = !hasAuditedPages\n ? 'error'\n : isCompleteBoundedSample(summary.terminationReason)\n ? 'complete'\n : 'partial'\n return {\n schemaVersion: summary.crawlSchemaVersion,\n label: '5-page Technical AEO sample',\n domain,\n rootUrl: summary.rootUrl,\n finalRootUrl: summary.finalRootUrl,\n status,\n score: hasAuditedPages ? summary.auditRollup.aggregateScore : null,\n pagesDiscovered: summary.pagesDiscovered,\n pagesFetched: summary.pagesFetched,\n pagesObserved: summary.pagesObserved,\n elapsedMs: summary.elapsedMs,\n terminationReason: summary.terminationReason,\n // Warnings may carry transport diagnostics from the crawler. Keep the\n // public record descriptive without persisting those raw messages.\n warnings: summary.warnings.slice(0, 4).map(() => 'Some optional crawl checks were unavailable.'),\n factors: hasAuditedPages\n ? summary.auditRollup.factors.slice(0, 16).map((factor) => ({\n id: factor.id,\n name: clip(factor.name, 100),\n averageScore: round(factor.averageScore),\n count: factor.count,\n }))\n : [],\n pages,\n siteMap,\n attemptedHosts,\n error: hasAuditedPages ? null : 'No public pages could be audited in the Technical AEO sample.',\n }\n}\n\n/**\n * A bounded sample that reached its OWN ceiling is complete, not partial.\n *\n * `summary.complete` means \"the crawler saw the whole site\", which this sample\n * is designed never to do: `maxPages` is 5, so any real site stops at\n * `max-pages` and every check reported `partial`. That marked the whole record\n * partial and painted an amber \"Partial result — Only completed checks are\n * included below. Failed checks are shown separately.\" over a run where\n * nothing failed. A caution banner on 100% of results is not a caution.\n *\n * Every `max-*` reason names a limit configured in\n * `VAL_TOWN_SITE_HEALTH_LIMITS`, so hitting one is the sample working. Anything\n * else — today only `root-host-redirect`, which means the crawl never reached\n * the host that was asked for — is a genuinely degraded outcome and stays\n * partial. The reason itself is reported either way, under \"Sample scope\".\n */\nfunction isCompleteBoundedSample(terminationReason: string | null | undefined): boolean {\n return !terminationReason || terminationReason.startsWith('max-')\n}\n\nfunction toPage(page: CrawlPageObservation): SiteHealthPageSample {\n const audit = page.audit\n return {\n url: clip(page.finalUrl ?? page.requestedUrl, 2_048),\n status: audit ? 'success' : 'error',\n score: audit ? round(audit.overallScore) : null,\n depth: page.depth,\n indexability: page.indexability?.state ?? null,\n factors: audit\n ? audit.factors.slice(0, 16).map((factor) => ({\n id: factor.id,\n name: clip(factor.name, 100),\n score: round(factor.score),\n applicable: factor.applicable ?? null,\n findings: factor.findings.slice(0, 3).map((finding) => ({\n code: clip(finding.code, 160),\n message: clip(finding.message, 500),\n })),\n recommendations: factor.recommendations.slice(0, 3).map((recommendation) => clip(recommendation, 500)),\n } satisfies FactorSample))\n : [],\n criticalDefects: audit\n ? audit.criticalDefects.slice(0, 8).map((defect) => ({\n id: defect.id,\n severity: defect.severity,\n detail: clip(defect.detail, 500),\n recommendation: clip(defect.recommendation, 500),\n }))\n : [],\n error: audit ? null : 'This page could not be audited.',\n }\n}\n\nfunction sortWorstFirst(left: SiteHealthPageSample, right: SiteHealthPageSample): number {\n if (left.score == null && right.score != null) return -1\n if (left.score != null && right.score == null) return 1\n return (left.score ?? 0) - (right.score ?? 0) || left.url.localeCompare(right.url)\n}\n\nfunction failedSample(domain: string, attemptedHosts: string[], error: string): SiteHealthSample {\n return {\n schemaVersion: '1.0',\n label: '5-page Technical AEO sample',\n domain,\n rootUrl: `https://${domain}/`,\n finalRootUrl: null,\n status: 'error',\n score: null,\n pagesDiscovered: 0,\n pagesFetched: 0,\n pagesObserved: 0,\n elapsedMs: 0,\n terminationReason: null,\n warnings: [],\n factors: [],\n pages: [],\n siteMap: null,\n attemptedHosts,\n error,\n }\n}\n\nfunction safeError(error: unknown): string {\n if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {\n return 'The Technical AEO sample timed out.'\n }\n return 'The Technical AEO sample could not complete.'\n}\n\nfunction clip(value: string, max: number): string {\n return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`\n}\n\nfunction round(value: number): number {\n return Math.round(value * 10) / 10\n}\n",[],[197,361,371],"37c32e25-97f8-4d9c-a502-d62cf5a68610","factor-order.ts","0d94f77c-a66e-11f1-8c55-1607ee4eb77e",167,["D",1788312702941],"/**\n * Display order for the audit factors: best score first, worst last.\n *\n * The audit engine returns its rollup alphabetically, which reads as a list of\n * names rather than a result. Sorting by score turns the same rows into a\n * ranking, so the strongest signals sit at the top and the work to do collects\n * at the bottom where it is easy to scan.\n *\n * Ordering is a reading decision over stored data, not part of the record, so it\n * is applied at read time. That keeps checks written before this change in the\n * new order too, and it is why both surfaces call the same comparator: the UI\n * and the MCP payload describe the same audit and must not disagree about which\n * factor is doing best.\n */\n\n/** What the order is decided on. `score` is null when nothing was measured. */\nexport interface FactorRank {\n score: number | null\n label: string\n}\n\n/**\n * An unmeasured factor sorts last, never as a zero. \"Not applicable to the\n * sampled page types\" is the absence of a measurement; ranking it below the\n * worst real score would claim it is worse than the worst thing found.\n */\nexport function compareFactorRank(a: FactorRank, b: FactorRank): number {\n const aScore = typeof a.score === 'number' && Number.isFinite(a.score) ? a.score : null\n const bScore = typeof b.score === 'number' && Number.isFinite(b.score) ? b.score : null\n if (aScore === null || bScore === null) {\n if (aScore !== bScore) return aScore === null ? 1 : -1\n } else if (aScore !== bScore) {\n return bScore - aScore\n }\n // Ties break by name so the same audit always draws the same list. Several\n // factors scoring 100 is the common case, not an edge case.\n return a.label.localeCompare(b.label)\n}\n\n/** Sort a copy, so a stored array is never reordered in place. */\nexport function orderFactors(items: readonly T[], rank: (item: T) => FactorRank): T[] {\n return [...items].sort((a, b) => compareFactorRank(rank(a), rank(b)))\n}\n",[],[197,361,379],"9872971b-6df7-4db3-a940-d575fb5071df",12,["D",1788292310513],[229,230,231,232],[197,361],"30900eea-d6de-4fb1-b86e-dbb1a2dddd6a","records.ts","93b29a9c-a63e-11f1-965f-1607ee4eb77e","9256932e-a63e-11f1-9a7d-1607ee4eb77e",217,["D",1788320555384],"/**\n * Shared record identity and lifetime rules.\n *\n * Both the HTTP app and the MCP endpoint resolve checks and decide whether one\n * is still readable. Two copies of either rule would drift silently: a\n * mismatched fingerprint makes the MCP endpoint miss cached work the UI can\n * see, and a mismatched expiry lets one surface serve a result the other has\n * already retired.\n */\nimport type { CheckRecord } from './types.ts'\n\n/** Caller-supplied questions, normalized for identity and for the prompt. */\nexport const MAX_USER_QUERIES = 3\nconst MIN_QUERY_CHARS = 3\nconst MAX_QUERY_CHARS = 200\n\n/**\n * Reuse identity for a domain check. It is versioned because it keys the cache\n * and the one-active-check index: changing what a check measures without\n * changing this prefix would let an old result answer a new question.\n *\n * v3 adds the brands each answer names, which is what mention share is built\n * from. A v2 record cannot satisfy a v3 request: it carries `namedBrands: null`\n * on every row, so the visitor would get a result silently missing half the\n * report and no way to tell why. Bumping the prefix retires those records at\n * the moment the signal set changed rather than at their own TTL.\n *\n * The caller's own questions are part of that identity. They change what the\n * check MEASURES, so two requests for one domain with different questions must\n * never share a result: without them in the key, the second caller silently\n * receives answers to the first caller's questions. Order is preserved rather\n * than sorted, so the key is exactly what was asked.\n */\nexport function checkFingerprint(domain: string, userQueries: readonly string[] = []): string {\n const base = `visibility-v3:${domain}`\n if (userQueries.length === 0) return base\n return `${base}|${userQueries.join('\\u0001')}`\n}\n\n/**\n * Trim, drop blanks, bound length, and cap the count. Returns the questions in\n * the order given; the generator fills whatever remains.\n */\nexport function normalizeUserQueries(input: unknown): string[] {\n const raw = typeof input === 'string' ? input.split('\\n') : Array.isArray(input) ? input : []\n const out: string[] = []\n for (const value of raw) {\n if (typeof value !== 'string') continue\n const trimmed = value.trim().replace(/\\s+/g, ' ')\n if (trimmed.length < MIN_QUERY_CHARS) continue\n out.push(trimmed.slice(0, MAX_QUERY_CHARS))\n if (out.length === MAX_USER_QUERIES) break\n }\n return out\n}\n\n/** A record with no `expiresAt` never expires; anything at or past it is gone. */\nexport function isCheckExpired(record: CheckRecord, at: Date): boolean {\n if (!record.expiresAt) return false\n const expiresAt = Date.parse(record.expiresAt)\n return Number.isFinite(expiresAt) && expiresAt <= at.getTime()\n}\n",[],[197,400,392],"runtime","0a24f5b2-dcb0-451c-b5f3-f2ebe7d595a3","check-result.ts","487e9c58-a7d1-11f1-8440-1607ee4eb77e",288,["D",1788465273092],"/**\n * What THIS val's check produces, and the reuse namespace that retires it.\n *\n * `@canonry/val-kit` is opaque to both: a `CheckRecord` carries\n * this schema through the kit's admission, lease, quota, and storage machinery\n * without the kit ever reading inside it, and `checkFingerprint` takes the\n * namespace as its first argument rather than inventing one. That is what lets\n * a second val store an entirely different result in the same table without\n * either product being able to serve the other's cached work.\n */\nimport type { VisibilityReport } from 'npm:@canonry/val-kit@0.1.0/visibility'\nimport type { SiteHealthSample } from '../site-health/types.ts'\n\n/**\n * The reuse namespace for this product. It is the FIRST field of every\n * fingerprint, which is both the 24h cache key and the one-active-check index.\n *\n * Bump it — and only it — when a change adds or removes a measured signal, so\n * records that lack the new signal stop satisfying new requests at the moment\n * the signal set changed rather than at their own TTL. `v3` is current because\n * checks now measure the brands each answer names. Never bump another\n * product's namespace, and never reuse one: two products keyed alike would\n * serve each other's results as cache hits.\n */\nexport const CHECK_FINGERPRINT_NAMESPACE = 'visibility-v3'\n\nexport const CHECK_RESULT_SCHEMA_VERSION = '1.0' as const\n\nexport interface CheckResult {\n schemaVersion: typeof CHECK_RESULT_SCHEMA_VERSION\n domain: string\n generatedAt: string\n visibility: VisibilityReport | null\n siteHealth: SiteHealthSample | null\n errors: Array<{ area: 'visibility' | 'site-health'; code: string; message: string }>\n}\n",[],[197,400,402],"eb2d53de-7095-4756-867a-252fd03349cc",["D",1788292309828],[226,227],[197,400],"b0e1ca82-2c27-4f6c-86a9-178e2585af0b","tools.ts","93d9894a-a63e-11f1-8fd4-1607ee4eb77e","9269bbca-a63e-11f1-8d00-1607ee4eb77e",291,["D",1788465273321],8,"/**\n * The MCP tool surface: reads over checks this val has already run, plus the\n * bundled skills for clients that do not implement MCP resources.\n *\n * Every tool but `start_check` is a read, and `start_check` runs the host's\n * full admission path — same global daily cap, same single execution lease,\n * same cache reuse — differing only in that it skips Turnstile, which an agent\n * cannot solve, and spends from its own tighter per-caller bucket. The global\n * cap is what bounds the bill; Turnstile bounds fairness, so this widens who\n * may spend the budget without widening the budget.\n *\n * Results are JSON in a text block rather than `structuredContent`, because\n * every client across both protocol eras renders text content, while typed\n * output is newer and unevenly implemented.\n */\nimport { type CheckRecord, checkFingerprint, type CheckStore, isCheckExpired } from 'npm:@canonry/val-kit@0.1.0/jobs'\nimport { listSkillResources, readSkillResource, skillIndex } from 'npm:@canonry/val-kit@0.1.0/mcp'\nimport { normalizePublicDomain, PublicUrlError } from 'npm:@canonry/val-kit@0.1.0/security'\nimport {\n computeMentionShare,\n computeShareOfVoice,\n type ShareOfVoice,\n type VisibilityEvidence,\n} from 'npm:@canonry/val-kit@0.1.0/visibility'\nimport { CHECK_FINGERPRINT_NAMESPACE, type CheckResult } from '../runtime/check-result.ts'\nimport { orderFactors } from '../site-health/factor-order.ts'\n\nconst CHECK_ID = /^[0-9a-f-]{36}$/i\n\nexport interface McpToolDefinition {\n name: string\n title: string\n description: string\n inputSchema: Record\n}\n\nexport interface McpToolResult {\n content: Array<{ type: 'text'; text: string }>\n isError?: boolean\n}\n\n/** Runs the host's full admission path; absent when the host disables MCP starts. */\nexport type StartCheckFn = (\n domain: string,\n remoteIp: string | null,\n queries: readonly string[],\n) => Promise<{ record: CheckRecord; reused: boolean }>\n\nexport interface McpToolContext {\n store: CheckStore\n now: () => Date\n startCheck?: StartCheckFn\n /** Edge-provided caller identity, used only as the quota subject. */\n remoteIp?: string | null\n}\n\nfunction ok(payload: unknown): McpToolResult {\n return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] }\n}\n\nfunction fail(message: string, hint?: string): McpToolResult {\n return {\n content: [{ type: 'text', text: JSON.stringify(hint ? { error: message, hint } : { error: message }, null, 2) }],\n isError: true,\n }\n}\n\nconst TARGET_SCHEMA = {\n type: 'object',\n properties: {\n checkId: { type: 'string', description: 'A check ID returned by a previous tool call or shown in the web UI.' },\n domain: {\n type: 'string',\n description:\n 'A domain such as \"example.com\". Resolves the most recent cached check; it never starts one. Use start_check ' +\n 'to run a fresh check.',\n },\n },\n additionalProperties: false,\n} as const\n\n/**\n * Resolve either addressing mode to a readable record.\n *\n * A domain lookup only ever finds work the val already did — it never starts\n * a check — so a miss is reported as a miss rather than quietly queuing paid\n * work the caller did not ask for.\n */\nasync function resolveCheck(\n context: McpToolContext,\n args: Record,\n): Promise<{ record: CheckRecord } | { error: McpToolResult }> {\n const checkId = typeof args.checkId === 'string' ? args.checkId.trim() : ''\n const domain = typeof args.domain === 'string' ? args.domain.trim() : ''\n\n if (!checkId && !domain) return { error: fail('Provide either \"checkId\" or \"domain\".') }\n\n const now = context.now()\n\n if (checkId) {\n if (!CHECK_ID.test(checkId)) return { error: fail(`\"${checkId}\" is not a valid check ID.`) }\n const record = await context.store.get(checkId)\n if (!record || isCheckExpired(record, now)) {\n return {\n error: fail(`No check found for ID \"${checkId}\".`, 'Public checks expire; run a new one from the web UI.'),\n }\n }\n return { record }\n }\n\n let normalized: string\n try {\n normalized = normalizePublicDomain(domain).domain\n } catch (error) {\n return { error: fail(error instanceof PublicUrlError ? error.message : 'Enter a valid public domain.') }\n }\n\n const record = await context.store.findReusable(\n checkFingerprint(CHECK_FINGERPRINT_NAMESPACE, normalized),\n now.toISOString(),\n )\n if (!record) {\n return {\n error: fail(\n `No cached check for \"${normalized}\".`,\n 'Run one with start_check, or from the web UI, then read it here.',\n ),\n }\n }\n return { record }\n}\n\n/** Shared envelope so every tool reports status and freshness the same way. */\nfunction recordEnvelope(record: CheckRecord) {\n return {\n checkId: record.id,\n domain: record.domain,\n status: record.status,\n createdAt: record.createdAt,\n updatedAt: record.updatedAt,\n expiresAt: record.expiresAt,\n error: record.errorCode ? { code: record.errorCode, message: record.errorMessage } : null,\n }\n}\n\n/**\n * Mention and citation are independent signals and are always reported as a\n * pair. A rate is null when nothing succeeded, never 0 — a provider failure is\n * an absent measurement, not a miss, and collapsing the two would report a site\n * as invisible when the check simply did not complete.\n */\nfunction visibilitySummary(record: CheckRecord) {\n const visibility = record.result?.visibility\n if (!visibility) return { measured: false as const }\n // Only a fully generated basket is guaranteed non-brand. Caller-supplied\n // queries may be branded, so labeling a mixed basket \"non-brand\" would break\n // the \"class travels with the number\" rule.\n const hasSuppliedQueries = record.userQueries.length > 0\n return {\n measured: true as const,\n scope: hasSuppliedQueries ? 'mixed' : 'non-brand',\n scopeNote: hasSuppliedQueries\n ? 'Includes caller-supplied queries, which may be branded, so rates are not restricted to non-brand queries.'\n : 'Queries are generated non-brand queries, so the project cannot be handed its own answer.',\n successfulChecks: visibility.summary.successfulChecks,\n failedChecks: visibility.summary.failedChecks,\n mentionRate: visibility.summary.mentionRate,\n citationRate: visibility.summary.citationRate,\n rateNote: 'Rates are over successful checks only. A null rate means nothing succeeded, not a rate of zero.',\n startedAt: visibility.startedAt,\n completedAt: visibility.completedAt,\n }\n}\n\nfunction siteHealthSummary(record: CheckRecord) {\n const siteHealth = record.result?.siteHealth\n if (!siteHealth) return { measured: false as const }\n return {\n measured: true as const,\n label: siteHealth.label,\n status: siteHealth.status,\n score: siteHealth.score,\n pagesDiscovered: siteHealth.pagesDiscovered,\n pagesFetched: siteHealth.pagesFetched,\n pagesObserved: siteHealth.pagesObserved,\n terminationReason: siteHealth.terminationReason,\n warnings: siteHealth.warnings,\n error: siteHealth.error,\n }\n}\n\n/** One share table on the wire, or null when that signal was not measurable. */\nfunction shareTable(share: ShareOfVoice | null, note: string) {\n if (!share) return null\n return {\n basis: share.basis,\n note,\n measuredAnswers: share.measuredAnswers,\n unattributedAnswers: share.unattributedAnswers,\n totalAppearances: share.totalAppearances,\n targetShare: share.targetShare,\n entries: share.entries,\n }\n}\n\n/**\n * The mention table is keyed by name, so the target's row needs the brand the\n * answers wrote, not its domain. Falls back to the domain when no answer named\n * it, which is the case where the row exists to report a zero.\n */\nfunction targetBrandLabel(evidence: readonly VisibilityEvidence[], domain: string): string {\n for (const row of evidence) {\n const name = row.matchedTerms.find((term) => !term.includes('.'))\n if (name) return name\n }\n return domain\n}\n\nfunction evidenceRow(evidence: VisibilityEvidence) {\n return {\n query: evidence.query,\n provider: evidence.provider,\n servedModel: evidence.servedModel,\n completedAt: evidence.completedAt,\n // Both signals, always. `null` on either means that check failed.\n mentioned: evidence.mentioned,\n matchedTerms: evidence.matchedTerms,\n cited: evidence.cited,\n matchedCitationDomains: evidence.matchedCitationDomains,\n matchedCitationUrls: evidence.matchedCitationUrls,\n citedDomains: evidence.citedDomains,\n sources: evidence.sources,\n searchQueries: evidence.searchQueries,\n // Brands this answer named, each verified to be written in it. Null means\n // the extraction did not run, not that the answer named nobody.\n namedBrands: evidence.namedBrands,\n retrievalStatus: evidence.retrievalStatus,\n answerText: evidence.answerText,\n error: evidence.error,\n }\n}\n\n/**\n * The conversion path. An agent that has just shown a user their coverage is\n * exactly where \"how do I get this properly\" gets asked, and without this it\n * would have to guess at an install command.\n */\nconst SELF_HOST_TOOL: McpToolDefinition = {\n name: 'self_host',\n title: 'How to self-host Canonry',\n description:\n 'How to run the full Canonry platform instead of this bounded sample: install command, repository, docs, and ' +\n 'what self-hosting adds over this endpoint. Call it when the user asks for more engines, scheduled tracking, ' +\n 'more queries, their own data, or how any of this actually works.',\n inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n}\n\nconst START_CHECK_TOOL: McpToolDefinition = {\n name: 'start_check',\n title: 'Run a new Canonry check',\n description:\n 'Run a fresh check for a domain: three grounded Gemini queries plus a bounded Technical AEO page sample. ' +\n 'Blocks until the check finishes, up to about 45 seconds, and returns the same shape as get_check. A domain ' +\n 'checked in the last 24 hours with the same questions returns the cached result immediately and costs nothing. ' +\n 'Daily limits apply.',\n inputSchema: {\n type: 'object',\n properties: {\n domain: { type: 'string', description: 'A domain such as \"example.com\".' },\n queries: {\n type: 'array',\n items: { type: 'string' },\n maxItems: 3,\n description:\n 'Optional. Up to 3 questions to put to the answer engine, used verbatim. Any remaining slots are filled ' +\n 'with questions generated for the site, so supplying none generates all three.',\n },\n },\n required: ['domain'],\n additionalProperties: false,\n },\n}\n\nconst READ_TOOLS: readonly McpToolDefinition[] = [\n SELF_HOST_TOOL,\n {\n name: 'get_check',\n title: 'Get a Canonry check',\n description:\n 'Status and headline numbers for one domain check: AI visibility (mention and citation rates over non-brand ' +\n 'queries) and the bounded Technical AEO site sample. Address it by checkId or by domain. Reads existing work ' +\n 'only — it never starts a new check.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'get_ai_visibility',\n title: 'Get AI visibility evidence',\n description:\n 'Per query and answer engine evidence for one check. Every row carries \"mentioned\" (the brand appears in the ' +\n 'answer text) and \"cited\" (the domain appears in the sources behind the answer) as independent signals, plus ' +\n 'the answer text, the cited domains and URLs, and the search queries the engine issued. A null signal means ' +\n 'that check failed and was not measured. Also returns two share tables, which are never mixed: citationShare ' +\n '(which domains the engine cited, and what share each holds) and mentionShare (which brands the answer prose ' +\n 'named). Every name in mentionShare was verified to be written in the answer it is counted against.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'get_site_health',\n title: 'Get Technical AEO site sample',\n description:\n 'The bounded Technical AEO sample for one check: overall score, per-factor averages, and per-page scores with ' +\n 'findings, critical defects, and recommendations, plus siteMap — the internal link graph observed by the same ' +\n 'crawl, as nodes and edges. A node is either crawled (it has a score and an indexability verdict) or merely ' +\n 'linked to (it has neither). This is a small page sample, not a whole-site audit.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'list_skills',\n title: 'List Canonry skill documents',\n description:\n 'Index of the bundled canonry (operator) and aero (analyst) skill documents available from this endpoint. ' +\n 'Entry points come first; read one with read_skill. Clients that support MCP resources can read the same ' +\n 'documents from resources/list.',\n inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n },\n {\n name: 'read_skill',\n title: 'Read a Canonry skill document',\n description: 'Read one skill document as markdown. Accepts a canonry-skill:// URI or a path such as ' +\n '\"aero/references/regression-playbook.md\". Start with an entry point from list_skills, then open the ' +\n 'reference the task calls for.',\n inputSchema: {\n type: 'object',\n properties: {\n uri: { type: 'string', description: 'A canonry-skill:// URI, or \"/\", or a bare reference path.' },\n },\n required: ['uri'],\n additionalProperties: false,\n },\n },\n]\n\n/** The advertised catalog. `start_check` appears only when the host can honour it. */\nexport function mcpTools(context: McpToolContext): readonly McpToolDefinition[] {\n return context.startCheck ? [...READ_TOOLS, START_CHECK_TOOL] : READ_TOOLS\n}\n\nexport async function callMcpTool(\n context: McpToolContext,\n name: string,\n args: Record,\n): Promise {\n switch (name) {\n case 'get_check': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n return ok({\n ...recordEnvelope(resolved.record),\n aiVisibility: visibilitySummary(resolved.record),\n siteHealth: siteHealthSummary(resolved.record),\n partialErrors: resolved.record.result?.errors ?? [],\n })\n }\n\n case 'get_ai_visibility': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n const visibility = resolved.record.result?.visibility\n if (!visibility) {\n return ok({\n ...recordEnvelope(resolved.record),\n measured: false,\n reason: resolved.record.status === 'queued' || resolved.record.status === 'running'\n ? 'The check is still running.'\n : 'This check has no AI visibility result.',\n })\n }\n const citationShare = computeShareOfVoice(visibility.evidence, visibility.domain)\n const mentionShare = computeMentionShare(\n visibility.evidence,\n targetBrandLabel(visibility.evidence, visibility.domain),\n )\n return ok({\n ...recordEnvelope(resolved.record),\n summary: visibilitySummary(resolved.record),\n // Two independent signals, two tables. Never one blended number: a site\n // can be cited without being named and named without being cited.\n citationShare: shareTable(\n citationShare,\n 'Share of the sources the engine used, by how many answers each domain appeared in.',\n ),\n mentionShare: shareTable(\n mentionShare,\n 'Share of the brands the answer prose named, by how many answers named each. Every name was verified to be ' +\n 'written in the answer it is counted against; null means the extraction did not run.',\n ),\n // Retained under its historical name so an existing caller does not\n // break. It has always been the citation table.\n shareOfVoice: shareTable(\n citationShare,\n 'Deprecated alias of citationShare. Use citationShare or mentionShare.',\n ),\n evidence: visibility.evidence.map(evidenceRow),\n })\n }\n\n case 'get_site_health': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n const siteHealth = resolved.record.result?.siteHealth\n if (!siteHealth) {\n return ok({\n ...recordEnvelope(resolved.record),\n measured: false,\n reason: resolved.record.status === 'queued' || resolved.record.status === 'running'\n ? 'The check is still running.'\n : 'This check has no Technical AEO result.',\n })\n }\n return ok({\n ...recordEnvelope(resolved.record),\n summary: siteHealthSummary(resolved.record),\n rootUrl: siteHealth.rootUrl,\n finalRootUrl: siteHealth.finalRootUrl,\n // Ranked best to worst, the same order the page shows. A factor with\n // no sampled page is unmeasured, so it ranks last rather than as a 0.\n factors: orderFactors(\n siteHealth.factors,\n (factor) => ({ score: factor.count > 0 ? factor.averageScore : null, label: factor.name }),\n ),\n pages: siteHealth.pages,\n // The internal-link graph from the same crawl. An agent asking \"what\n // links to this weak page\" needs the edges, not just the scores.\n siteMap: siteHealth.siteMap,\n })\n }\n\n case 'start_check': {\n if (!context.startCheck) return fail('Starting a check is not enabled on this endpoint.')\n const domain = typeof args.domain === 'string' ? args.domain.trim() : ''\n if (!domain) return fail('Provide a \"domain\".')\n try {\n const queries = Array.isArray(args.queries) ? args.queries : []\n const { record, reused } = await context.startCheck(domain, context.remoteIp ?? null, queries)\n return ok({\n ...recordEnvelope(record),\n reused,\n aiVisibility: visibilitySummary(record),\n siteHealth: siteHealthSummary(record),\n partialErrors: record.result?.errors ?? [],\n })\n } catch (error) {\n // The host throws typed admission failures (quota, capacity, invalid\n // domain). Their messages are already caller-safe and actionable.\n return fail(error instanceof Error ? error.message : 'The check could not be started.')\n }\n }\n\n case 'self_host':\n return ok({\n summary:\n 'This endpoint is a bounded sample. Canonry is the full platform it samples: open source, self-hosted, ' +\n 'agent-first, with your own data in local SQLite.',\n install: 'npm install -g @canonry/canonry',\n quickstart: [\n 'npm install -g @canonry/canonry',\n 'canonry init',\n 'canonry project create my-site --domain example.com --country US --language en',\n 'canonry query add my-site \"best example widgets\"',\n 'canonry run my-site',\n 'canonry visibility-stats my-site',\n ],\n repository: 'https://github.com/Canonry/canonry',\n website: 'https://canonry.ai',\n package: 'https://www.npmjs.com/package/@canonry/canonry',\n license: 'FSL-1.1-ALv2',\n whatSelfHostingAdds: [\n 'All four answer engines — Gemini, ChatGPT, Claude, Perplexity — not Gemini alone.',\n 'Unlimited tracked queries and scheduled sweeps, instead of 3 generated queries on demand.',\n 'Whole-site technical audits, instead of a 5-page sample.',\n 'History, trends, competitor mention share, and regression insights over time.',\n 'Google Search Console, GA4, Bing, Business Profile, and server-side traffic joined to the same view.',\n 'Your own MCP server (canonry-mcp, 188 tools) and the built-in Aero analyst agent.',\n 'Your data stays in your own SQLite database.',\n ],\n skills: 'The canonry and aero skill documents served by this endpoint are the same playbooks a local install ' +\n 'ships. Read canonry-skill://canonry/SKILL.md to operate the CLI.',\n })\n\n case 'list_skills':\n return ok({ skills: skillIndex(), resources: listSkillResources().length })\n\n case 'read_skill': {\n const uri = typeof args.uri === 'string' ? args.uri.trim() : ''\n if (!uri) return fail('Provide a skill document \"uri\".')\n const contents = readSkillResource(uri)\n if (!contents) {\n return fail(`No skill document matches \"${uri}\".`, 'Call list_skills for the available URIs.')\n }\n return { content: [{ type: 'text', text: contents.text }] }\n }\n\n default:\n return null\n }\n}\n",[],[197,423,414],"mcp","05a202bf-f07a-4722-9a33-c8711cf59dd0","server.ts","97ad3ed6-a63e-11f1-adb4-1607ee4eb77e",292,["D",1788465273441],"/**\n * MCP method dispatch and the HTTP handler for the `/mcp` endpoint.\n *\n * The endpoint is anonymous, which is a deliberate consequence of what it\n * exposes: checks on this val are already public — the web UI serves any of\n * them from `/api/checks/:id` without a credential — and the skills ship in a\n * public npm package. A token would gate nothing already unreachable, while\n * making the endpoint useless as something an agent is simply pointed at.\n *\n * `start_check` is the one tool that spends. It is admitted by per-caller\n * quota rather than by a credential, under the same global daily cap as the\n * browser, so an anonymous caller can consume its share of the day's budget\n * but never enlarge it.\n */\nimport {\n isAllowedOrigin,\n jsonRpcError,\n JsonRpcErrorCodes,\n type JsonRpcResponse,\n jsonRpcResult,\n listSkillResources,\n type ParsedMcpRequest,\n parseMcpRequest,\n readSkillResource,\n SUPPORTED_PROTOCOL_VERSIONS,\n} from 'npm:@canonry/val-kit@0.1.0/mcp'\nimport { callMcpTool, type McpToolContext, mcpTools, type StartCheckFn } from './tools.ts'\n\n/** Version of this MCP surface, not of the Canonry package the val samples. */\nexport const MCP_SERVER_VERSION = '1.0.0'\n\nconst MAX_BODY_BYTES = 262_144\n\n// Named for what this endpoint is, not for the platform it samples. Calling it\n// `canonry` would tell an agent it had the whole product, when it has three\n// queries and five pages.\nconst SERVER_INFO = {\n name: 'ai-visibility-check',\n title: 'AI Visibility Check (by Canonry)',\n version: MCP_SERVER_VERSION,\n} as const\n\nconst INSTRUCTIONS = [\n 'AI Visibility Check is a free, bounded sample of Canonry. It measures whether an AI answer engine mentions a',\n 'brand and cites its domain. One check is 3 generated non-brand queries against Gemini plus a 5-page technical',\n 'audit: enough to see the signal, not enough to monitor a site. Canonry itself is open source, self-hosted,',\n 'tracks Gemini, ChatGPT, Claude and Perplexity on a schedule, and has no such limits. Call self_host for that.',\n '',\n 'Two signals are tracked separately and must never be merged: \"mentioned\" means the brand appears in the answer',\n 'text, \"cited\" means the domain appears in the sources behind the answer. A model can do either, both, or neither.',\n 'A null signal means that check failed and was not measured — it is not a miss.',\n '',\n 'Start with list_skills and read the aero entry point for how to interpret and report on coverage; read the canonry',\n 'entry point for how to operate the CLI. Then use get_check for headline numbers, get_ai_visibility for per-query',\n 'evidence, and get_site_health for the Technical AEO page sample.',\n '',\n 'get_check, get_ai_visibility, and get_site_health read existing checks and never spend. start_check runs a fresh',\n 'one, blocks for up to about 45 seconds, and is subject to daily limits; a domain checked in the last 24 hours',\n 'returns from cache at no cost. Prefer reading before starting.',\n].join('\\n')\n\nexport interface McpHandlerOptions {\n store: McpToolContext['store']\n now?: () => Date\n /** Omit to keep the endpoint strictly read-only. */\n startCheck?: StartCheckFn\n}\n\nfunction jsonResponse(body: JsonRpcResponse, status = 200): Response {\n return new Response(JSON.stringify(body), {\n status,\n headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },\n })\n}\n\nasync function readLimitedBody(request: Request): Promise {\n const declared = Number(request.headers.get('content-length'))\n if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) return null\n if (!request.body) return ''\n const reader = request.body.getReader()\n const chunks: Uint8Array[] = []\n let length = 0\n while (true) {\n const next = await reader.read()\n if (next.done) break\n length += next.value.byteLength\n if (length > MAX_BODY_BYTES) {\n await reader.cancel()\n return null\n }\n chunks.push(next.value)\n }\n const merged = new Uint8Array(length)\n let offset = 0\n for (const chunk of chunks) {\n merged.set(chunk, offset)\n offset += chunk.byteLength\n }\n return new TextDecoder().decode(merged)\n}\n\n/**\n * Val injects `cf-connecting-ip`. `x-forwarded-for` is caller-controlled on a\n * public val and is deliberately ignored, so a caller cannot mint a fresh\n * quota identity per request.\n */\nfunction edgeIp(request: Request): string | null {\n const value = request.headers.get('cf-connecting-ip')?.trim()\n return value && value.length <= 128 ? value : null\n}\n\n/** Dispatch one parsed message. Returns null for a notification, which gets 202. */\nasync function dispatch(\n context: McpToolContext,\n request: ParsedMcpRequest,\n): Promise<{ response: JsonRpcResponse; status: number } | null> {\n const { message, protocolVersion } = request\n const id = message.id ?? null\n const params = message.params ?? {}\n\n switch (message.method) {\n case 'initialize': {\n // Echo a version the caller asked for when it is one we speak, so a\n // legacy client stays in its own era instead of being pushed forward\n // into rules it does not implement. A client that declared its version\n // only in the `MCP-Protocol-Version` header and omitted it from params\n // still gets its own era back, because `protocolVersion` carries what\n // the envelope declared; falling through to the newest version would\n // answer a 2025 client with 2026 rules it has no code for.\n const requested = typeof params.protocolVersion === 'string' ? params.protocolVersion : null\n const negotiated = requested && (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(requested)\n ? requested\n : protocolVersion\n return {\n status: 200,\n response: jsonRpcResult(id, {\n protocolVersion: negotiated,\n capabilities: { tools: { listChanged: false }, resources: { listChanged: false, subscribe: false } },\n serverInfo: SERVER_INFO,\n instructions: INSTRUCTIONS,\n }),\n }\n }\n\n // Accepted so a legacy handshake completes. There is no session to advance.\n case 'notifications/initialized':\n case 'notifications/cancelled':\n return null\n\n case 'ping':\n return { status: 200, response: jsonRpcResult(id, {}) }\n\n case 'tools/list':\n return { status: 200, response: jsonRpcResult(id, { tools: mcpTools(context) }) }\n\n case 'tools/call': {\n const name = typeof params.name === 'string' ? params.name : ''\n const args = params.arguments && typeof params.arguments === 'object' && !Array.isArray(params.arguments)\n ? params.arguments as Record\n : {}\n if (!name) {\n return {\n status: 200,\n response: jsonRpcError(id, JsonRpcErrorCodes.invalidParams, 'tools/call requires a \"name\".'),\n }\n }\n const result = await callMcpTool(context, name, args)\n if (!result) {\n return {\n status: 200,\n response: jsonRpcError(id, JsonRpcErrorCodes.invalidParams, `Unknown tool \"${name}\".`),\n }\n }\n return { status: 200, response: jsonRpcResult(id, result) }\n }\n\n case 'resources/list':\n return { status: 200, response: jsonRpcResult(id, { resources: listSkillResources() }) }\n\n // Answered rather than refused: several clients probe both during startup,\n // and a method-not-found there reads as a broken server.\n case 'resources/templates/list':\n return { status: 200, response: jsonRpcResult(id, { resourceTemplates: [] }) }\n\n case 'prompts/list':\n return { status: 200, response: jsonRpcResult(id, { prompts: [] }) }\n\n case 'resources/read': {\n const uri = typeof params.uri === 'string' ? params.uri : ''\n const contents = uri ? readSkillResource(uri) : null\n if (!contents) {\n return {\n status: 200,\n response: jsonRpcError(id, JsonRpcErrorCodes.invalidParams, `Resource not found: \"${uri}\".`),\n }\n }\n return { status: 200, response: jsonRpcResult(id, { contents: [contents] }) }\n }\n\n default:\n // A notification (no id) must never be answered, even for an unknown\n // method: returning null yields the 202 no-body the handler sends for\n // notifications. A roots-capable client's notifications/roots/list_changed\n // would otherwise get a 404 it can read as \"endpoint gone\".\n if (request.isNotification) return null\n // Streamable HTTP pairs an unknown request with 404, which is how a client\n // tells a modern server apart from a legacy endpoint that lacks this route.\n return {\n status: 404,\n response: jsonRpcError(id, JsonRpcErrorCodes.methodNotFound, `Unknown method \"${message.method}\".`),\n }\n }\n}\n\n/** Handle one POST to the MCP endpoint. */\nexport function createMcpHandler(options: McpHandlerOptions): (request: Request) => Promise {\n const base: McpToolContext = {\n store: options.store,\n now: options.now ?? (() => new Date()),\n startCheck: options.startCheck,\n }\n\n return async (request: Request): Promise => {\n if (request.method !== 'POST') {\n // The modern revision removed the GET stream and DELETE teardown.\n return jsonResponse(\n jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'The MCP endpoint accepts POST only.'),\n 405,\n )\n }\n\n if (!isAllowedOrigin(request.headers, request.url)) {\n return jsonResponse(jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Origin not allowed.'), 403)\n }\n\n const raw = await readLimitedBody(request)\n if (raw === null) {\n return jsonResponse(jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Request body is too large.'), 413)\n }\n\n let body: unknown\n try {\n body = JSON.parse(raw)\n } catch {\n return jsonResponse(jsonRpcError(null, JsonRpcErrorCodes.parseError, 'Request body is not valid JSON.'), 400)\n }\n\n const parsed = parseMcpRequest(request.headers, body)\n if (!parsed.ok) return jsonResponse(parsed.response, parsed.status)\n\n let outcome: Awaited>\n try {\n outcome = await dispatch({ ...base, remoteIp: edgeIp(request) }, parsed.request)\n } catch {\n // Never surface an internal message; a store failure can carry\n // deployment detail that does not belong on a public endpoint.\n return jsonResponse(\n jsonRpcError(parsed.request.message.id ?? null, JsonRpcErrorCodes.internalError, 'Internal error.'),\n 200,\n )\n }\n\n if (!outcome) {\n if (!parsed.request.isNotification) {\n // A request that dispatched as a notification would otherwise hang the\n // caller waiting for a response that is never coming.\n return jsonResponse(\n jsonRpcError(\n parsed.request.message.id ?? null,\n JsonRpcErrorCodes.invalidRequest,\n `\"${parsed.request.message.method}\" is a notification and must be sent without an \"id\".`,\n ),\n 400,\n )\n }\n return new Response(null, { status: 202, headers: { 'cache-control': 'no-store' } })\n }\n\n return jsonResponse(outcome.response, outcome.status)\n }\n}\n",[],[197,423,425],"ccfbc8ea-f94f-4497-a994-e882d008b341","resources.ts","93b7d796-a63e-11f1-9193-1607ee4eb77e",39,["D",1788292312132],"/**\n * The bundled `canonry` and `aero` skills, served as MCP resources.\n *\n * This is the half of the endpoint that makes the other half worth connecting\n * to. Coverage numbers on their own need interpretation — which signal moved,\n * whether the denominator is comparable, what to do next — and that\n * interpretation is exactly what the two skills already write down. An agent\n * that reads them alongside the data behaves like an analyst instead of a JSON\n * pretty-printer.\n *\n * `resources/list` returns entry points and references together, with\n * `SKILL.md` first, so a client can load the entry point and open a reference\n * only when the task calls for it. That is the same contract a local install\n * has, so nothing new has to be explained to the agent.\n */\nimport type { SkillDocument } from './skill-types.ts'\nimport { SKILL_DOCUMENTS } from './skills/catalog.ts'\n\nexport const SKILL_RESOURCE_MIME_TYPE = 'text/markdown'\n\nexport interface McpResourceDescriptor {\n uri: string\n name: string\n title: string\n description: string\n mimeType: string\n}\n\nexport interface McpResourceContents {\n uri: string\n mimeType: string\n text: string\n}\n\n/** Entry points first, then references, each group alphabetical by URI. */\nconst ORDERED_DOCUMENTS: readonly SkillDocument[] = [...SKILL_DOCUMENTS].sort((a, b) => {\n if (a.entryPoint !== b.entryPoint) return a.entryPoint ? -1 : 1\n return a.uri.localeCompare(b.uri)\n})\n\nconst BY_URI = new Map(ORDERED_DOCUMENTS.map((document) => [document.uri, document]))\n\n/**\n * Also index by `/` and by bare path so a caller that reconstructs\n * a reference from prose in `SKILL.md` — which links them as\n * `references/reporting.md` — reaches the document instead of a not-found.\n */\nconst BY_ALIAS = new Map()\nfor (const document of ORDERED_DOCUMENTS) {\n BY_ALIAS.set(`${document.skill}/${document.path}`, document)\n const bare = document.path\n // A bare path is ambiguous only if two skills share it; first one wins and\n // the qualified form above always remains exact.\n if (!BY_ALIAS.has(bare)) BY_ALIAS.set(bare, document)\n}\n\nexport function listSkillResources(): McpResourceDescriptor[] {\n return ORDERED_DOCUMENTS.map((document) => ({\n uri: document.uri,\n name: `${document.skill}/${document.path}`,\n title: document.title,\n description: document.entryPoint\n ? `Entry point for the ${document.skill} skill. ${document.description}`\n : document.description,\n mimeType: SKILL_RESOURCE_MIME_TYPE,\n }))\n}\n\nexport function findSkillDocument(uri: string): SkillDocument | null {\n const trimmed = uri.trim()\n return BY_URI.get(trimmed) ?? BY_ALIAS.get(trimmed.replace(/^canonry-skill:\\/\\//, '')) ?? null\n}\n\nexport function readSkillResource(uri: string): McpResourceContents | null {\n const document = findSkillDocument(uri)\n if (!document) return null\n return { uri: document.uri, mimeType: SKILL_RESOURCE_MIME_TYPE, text: document.content }\n}\n\n/** Compact index used by the `read_skill` tool, for clients without resource support. */\nexport function skillIndex(): Array<{ uri: string; skill: string; path: string; title: string; entryPoint: boolean }> {\n return ORDERED_DOCUMENTS.map((document) => ({\n uri: document.uri,\n skill: document.skill,\n path: document.path,\n title: document.title,\n entryPoint: document.entryPoint,\n }))\n}\n",[],[197,423,433],"67c1d767-f5f3-4ebd-bca5-d25acdc403f7","protocol.ts","94264780-a63e-11f1-a387-1607ee4eb77e",229,["D",1788372559904],"/**\n * JSON-RPC framing and Streamable HTTP envelope rules for the MCP endpoint.\n *\n * Two protocol eras have to work at once. Revision `2026-07-28` removed\n * protocol-level sessions and the GET stream, and moved per-request metadata\n * into the body, so a modern client can POST `tools/call` with no handshake at\n * all. Every client shipping today still opens with `initialize` and expects a\n * negotiated version back. Refusing either one would make the endpoint useless\n * to half its callers, so this module speaks both and keys the strict checks\n * off the version the caller actually declared.\n *\n * Responses are always `application/json`. Both eras permit it for a request\n * that has nothing to stream, and every tool here returns a single value, so\n * an SSE encoder would be machinery with no purpose.\n */\n\n/** Newest first. The head is what an unversioned or unknown request negotiates to. */\nexport const SUPPORTED_PROTOCOL_VERSIONS = [\n '2026-07-28',\n '2025-11-25',\n '2025-06-18',\n '2025-03-26',\n] as const\n\nexport type ProtocolVersion = (typeof SUPPORTED_PROTOCOL_VERSIONS)[number]\n\nexport const LATEST_PROTOCOL_VERSION: ProtocolVersion = SUPPORTED_PROTOCOL_VERSIONS[0]\n\n/**\n * The first revision that mirrors body fields into headers and requires them to\n * agree. Older callers never send `Mcp-Method`, so validating them against it\n * would reject every compliant legacy client.\n */\nconst HEADER_VALIDATION_FROM: ProtocolVersion = '2026-07-28'\n\nexport const JSON_RPC_VERSION = '2.0'\n\nexport const JsonRpcErrorCodes = {\n parseError: -32700,\n invalidRequest: -32600,\n methodNotFound: -32601,\n invalidParams: -32602,\n internalError: -32603,\n /** Streamable HTTP: headers disagree with the body, or a required one is missing. */\n headerMismatch: -32020,\n} as const\n\nexport type JsonRpcId = string | number | null\n\nexport interface JsonRpcRequest {\n jsonrpc: typeof JSON_RPC_VERSION\n id?: JsonRpcId\n method: string\n params?: Record\n}\n\nexport interface JsonRpcError {\n code: number\n message: string\n data?: unknown\n}\n\nexport interface JsonRpcSuccessResponse {\n jsonrpc: typeof JSON_RPC_VERSION\n id: JsonRpcId\n result: unknown\n}\n\nexport interface JsonRpcErrorResponse {\n jsonrpc: typeof JSON_RPC_VERSION\n id: JsonRpcId\n error: JsonRpcError\n}\n\nexport type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse\n\nexport function jsonRpcResult(id: JsonRpcId, result: unknown): JsonRpcSuccessResponse {\n return { jsonrpc: JSON_RPC_VERSION, id, result }\n}\n\nexport function jsonRpcError(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcErrorResponse {\n return { jsonrpc: JSON_RPC_VERSION, id, error: data === undefined ? { code, message } : { code, message, data } }\n}\n\nexport function isSupportedProtocolVersion(value: string): value is ProtocolVersion {\n return (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(value)\n}\n\nfunction requiresHeaderValidation(version: ProtocolVersion): boolean {\n // Dated versions compare correctly as strings; they are all `YYYY-MM-DD`.\n return version >= HEADER_VALIDATION_FROM\n}\n\n/** A parsed, envelope-valid POST body plus the metadata the transport carries. */\nexport interface ParsedMcpRequest {\n message: JsonRpcRequest\n /** Absent `id` means a notification, which is answered with 202 and no body. */\n isNotification: boolean\n protocolVersion: ProtocolVersion\n}\n\nexport type McpRequestParseResult =\n | { ok: true; request: ParsedMcpRequest }\n | { ok: false; status: number; response: JsonRpcErrorResponse }\n\nfunction readMetaProtocolVersion(params: Record | undefined): string | null {\n const meta = params?._meta\n if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return null\n const value = (meta as Record)['io.modelcontextprotocol/protocolVersion']\n return typeof value === 'string' ? value : null\n}\n\n/**\n * Undo the `=?base64?…?=` sentinel a client uses for a header value that cannot\n * be written as plain ASCII. Comparing the raw sentinel against the body would\n * report a mismatch on every non-ASCII tool name.\n */\nfunction decodeHeaderValue(value: string): string {\n if (!value.startsWith('=?base64?') || !value.endsWith('?=')) return value\n try {\n const encoded = value.slice('=?base64?'.length, -'?='.length)\n return new TextDecoder().decode(Uint8Array.from(atob(encoded), (char) => char.charCodeAt(0)))\n } catch {\n return value\n }\n}\n\n/**\n * Validate the HTTP envelope and JSON-RPC shape of one POST.\n *\n * Returns the negotiated protocol version alongside the message so the\n * dispatcher never has to re-derive it. A failure carries both the HTTP status\n * and the JSON-RPC body, because Streamable HTTP pairs specific statuses with\n * specific error codes and a caller distinguishes eras by reading them.\n */\nexport function parseMcpRequest(headers: Headers, body: unknown): McpRequestParseResult {\n if (!body || typeof body !== 'object' || Array.isArray(body)) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Request body must be a JSON-RPC object.'),\n }\n }\n\n const message = body as Record\n if (message.jsonrpc !== JSON_RPC_VERSION) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Expected \"jsonrpc\": \"2.0\".'),\n }\n }\n if (typeof message.method !== 'string' || message.method.length === 0) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Request is missing a \"method\".'),\n }\n }\n if ('result' in message || 'error' in message) {\n // Clients never send responses on this transport in any era.\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Clients must not send JSON-RPC responses.'),\n }\n }\n\n const rawId = message.id\n const isNotification = rawId === undefined\n const id: JsonRpcId = typeof rawId === 'string' || typeof rawId === 'number' ? rawId : null\n const params = message.params && typeof message.params === 'object' && !Array.isArray(message.params)\n ? message.params as Record\n : undefined\n\n const headerVersion = headers.get('mcp-protocol-version')?.trim() || null\n const bodyVersion = readMetaProtocolVersion(params)\n\n // A version present in both places must agree before either is trusted; a\n // proxy routing on the header and a server reading the body would otherwise\n // act on different values.\n if (headerVersion && bodyVersion && headerVersion !== bodyVersion) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(\n id,\n JsonRpcErrorCodes.headerMismatch,\n `MCP-Protocol-Version header \"${headerVersion}\" does not match the body value \"${bodyVersion}\".`,\n ),\n }\n }\n\n const declared = headerVersion ?? bodyVersion\n\n // An `initialize` with no declared version is a legacy client opening a\n // handshake; it negotiates inside the method. Anything else defaults to the\n // newest version, which is also the one whose rules are strictest.\n let protocolVersion: ProtocolVersion = LATEST_PROTOCOL_VERSION\n if (declared !== null) {\n if (!isSupportedProtocolVersion(declared)) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(\n id,\n JsonRpcErrorCodes.invalidRequest,\n `Unsupported protocol version \"${declared}\".`,\n { supported: [...SUPPORTED_PROTOCOL_VERSIONS] },\n ),\n }\n }\n protocolVersion = declared\n }\n\n if (declared !== null && requiresHeaderValidation(protocolVersion)) {\n const mismatch = validateMirroredHeaders(headers, message.method, params)\n if (mismatch) {\n return { ok: false, status: 400, response: jsonRpcError(id, JsonRpcErrorCodes.headerMismatch, mismatch) }\n }\n }\n\n return {\n ok: true,\n request: {\n message: { jsonrpc: JSON_RPC_VERSION, id, method: message.method, params },\n isNotification,\n protocolVersion,\n },\n }\n}\n\n/** `Mcp-Method` and, where the method carries a name, `Mcp-Name` must mirror the body. */\nfunction validateMirroredHeaders(\n headers: Headers,\n method: string,\n params: Record | undefined,\n): string | null {\n const headerMethod = headers.get('mcp-method')?.trim()\n if (!headerMethod) return 'Mcp-Method header is required.'\n if (headerMethod !== method) {\n return `Mcp-Method header \"${headerMethod}\" does not match the body method \"${method}\".`\n }\n\n const namedMethods: Record = {\n 'tools/call': 'name',\n 'resources/read': 'uri',\n 'prompts/get': 'name',\n }\n const nameField = namedMethods[method]\n if (!nameField) return null\n\n const bodyValue = params?.[nameField]\n if (typeof bodyValue !== 'string') return null\n\n const headerName = headers.get('mcp-name')\n if (headerName === null) return 'Mcp-Name header is required for this method.'\n const decoded = decodeHeaderValue(headerName.trim())\n if (decoded !== bodyValue) {\n return `Mcp-Name header \"${decoded}\" does not match the body value \"${bodyValue}\".`\n }\n return null\n}\n\n/**\n * Reject a cross-origin browser caller.\n *\n * A non-browser MCP client sends no `Origin` at all, so this is only ever\n * exercised by a page in a browser. Allowing same-origin and absent covers\n * every real client while closing the DNS-rebinding hole the transport spec\n * calls out.\n */\nexport function isAllowedOrigin(headers: Headers, requestUrl: string): boolean {\n const origin = headers.get('origin')\n if (!origin) return true\n try {\n return new URL(origin).origin === new URL(requestUrl).origin\n } catch {\n return false\n }\n}\n",[],[197,423,441],"ae91bccc-3e31-4356-834f-cb508c834a4f",["D",1788292309949],[221,222,223,224],[197,423],"3474782c-f664-414d-a7aa-e610c40f82fd","public-check.ts","960dcd34-a63e-11f1-bfe2-1607ee4eb77e","92af4352-a63e-11f1-9f99-1607ee4eb77e",298,["D",1788465274456],"import {\n type CheckStore,\n PUBLIC_CHECK_EXECUTION_LEASE_MS,\n PUBLIC_CHECK_EXECUTION_LEASE_NAME,\n PUBLIC_CHECK_UNAVAILABLE,\n type PublicCheckDispatchOptions,\n type PublicCheckRunner,\n} from 'npm:@canonry/val-kit@0.1.0/jobs'\nimport {\n safeProviderErrorMessage,\n type VisibilityProbePort,\n type VisibilityReport,\n} from 'npm:@canonry/val-kit@0.1.0/visibility'\nimport { CHECK_RESULT_SCHEMA_VERSION, type CheckResult } from '../runtime/check-result.ts'\nimport type { SiteHealthRunner, SiteHealthSample } from '../site-health/types.ts'\n\n/**\n * Ceiling for one check's provider work. The visibility probe and the site\n * crawl run under it in parallel, so this is the budget the probe phase's own\n * planner + probes + extraction deadlines have to fit inside.\n */\nexport const PUBLIC_CHECK_WORK_BUDGET_MS = 45_000\n\nconst SITE_HEALTH_TIMEOUT_ERROR = 'The Technical AEO sample timed out.'\nconst SITE_HEALTH_NO_PUBLIC_PAGES_ERROR = 'No public pages could be audited in the Technical AEO sample.'\nconst SITE_HEALTH_GENERIC_ERROR = 'The Technical AEO sample could not complete.'\nconst VISIBILITY_GENERIC_ERROR = 'The AI Visibility sample could not complete.'\n\n// `SiteHealthSample.error` crosses from the crawler adapter into the public\n// durable record. These are the only strings emitted by the local runner that\n// are safe to preserve; every other string is treated as a transport detail.\nconst SAFE_SITE_HEALTH_ERRORS = new Set([\n SITE_HEALTH_TIMEOUT_ERROR,\n SITE_HEALTH_NO_PUBLIC_PAGES_ERROR,\n SITE_HEALTH_GENERIC_ERROR,\n])\n\n/**\n * Why one query in a check could not be measured, in the visitor's words.\n *\n * The runner already classifies a probe failure into one of a small closed set\n * of strings, and none of them carry a provider body, a request id, or a\n * credential. This sanitizer used to replace all of them with a single\n * \"This answer-engine check was unavailable.\", which meant the reason existed\n * for one function call and was then destroyed: nothing is logged either, so a\n * row reading \"Not measured\" could not be explained afterwards by anyone,\n * including the operator.\n *\n * Translated rather than passed through, for two reasons. The upstream wording\n * says \"provider\", which is not a word this page uses. And a sanitizer must not\n * trust its input: an adapter that one day puts a transport dump in `message`\n * falls through to the generic sentence instead of publishing it.\n */\nconst PUBLIC_PROBE_ERRORS = new Map([\n ['The provider request timed out.', 'The answer engine did not respond in time.'],\n ['The provider request was cancelled.', 'This check was cancelled before the answer engine replied.'],\n ['The provider rate-limited this request.', 'The answer engine rate-limited this check.'],\n ['The provider was temporarily unavailable.', 'The answer engine was temporarily unavailable.'],\n ['The provider credentials were rejected.', 'This check could not be authorized with the answer engine.'],\n ['The provider response contained no answer text.', 'The answer engine returned no answer text.'],\n ['The provider answer was cut off at the length limit.', 'The answer engine ran out of room mid-answer.'],\n ['The provider declined to answer this query.', 'The answer engine declined to answer this question.'],\n [\n 'The provider stopped the answer to avoid reciting a source.',\n 'The answer engine stopped short to avoid quoting a source.',\n ],\n ['The provider does not support the language of this query.', 'The answer engine does not support this language.'],\n ['The provider ended the answer on an internal tool error.', 'The answer engine hit an internal error mid-answer.'],\n [\n 'The provider ended the answer without writing anything.',\n 'The answer engine finished without saying anything for this question.',\n ],\n ['The provider stopped the answer for an unstated reason.', 'The answer engine stopped without giving a reason.'],\n ['The provider response has an invalid requested model.', 'The answer engine reported an unusable model.'],\n ['The provider request failed.', 'The answer engine did not return an answer.'],\n])\n\n/** Exported for the test that pins every runner failure to a public sentence. */\nexport function publicProbeError(message: string | null): string | null {\n if (message === null) return null\n return PUBLIC_PROBE_ERRORS.get(message) ?? PUBLIC_CHECK_UNAVAILABLE\n}\n\nexport class PublicQuotaError extends Error {\n override name = 'PublicQuotaError'\n constructor(readonly scope: 'client' | 'global') {\n super(scope === 'client' ? 'Daily check limit reached.' : 'The public check is at capacity. Try again tomorrow.')\n }\n}\n\nexport interface PublicCheckRunnerOptions {\n store: CheckStore\n visibilityProbe: VisibilityProbePort | null\n siteHealthRunner: SiteHealthRunner\n ttlMs: number\n now?: () => Date\n}\n\nexport function createPublicCheckRunner(options: PublicCheckRunnerOptions): PublicCheckRunner {\n const now = options.now ?? (() => new Date())\n return {\n async run(checkId, dispatchOptions: PublicCheckDispatchOptions = {}) {\n const owner = dispatchOptions.executionLeaseOwner ?? crypto.randomUUID()\n const started = now()\n const jobLeaseUntil = new Date(started.getTime() + PUBLIC_CHECK_EXECUTION_LEASE_MS).toISOString()\n // A supplied reservation must be released even when the durable job\n // vanished before this request-bound runner could claim it.\n let shouldReleaseExecutionLease = dispatchOptions.executionLeaseOwner !== undefined\n\n try {\n const record = await options.store.claimJob(checkId, owner, started.toISOString(), jobLeaseUntil)\n if (!record) return 'ignored'\n\n // Renew an admission reservation (or claim a direct-run lease) after\n // the durable job claim. A slow admission must never reach provider\n // work on a reservation that has expired in the meantime.\n const renewalAt = now()\n const executionLeaseUntil = new Date(renewalAt.getTime() + PUBLIC_CHECK_EXECUTION_LEASE_MS).toISOString()\n const hasExecutionLease = await options.store.claimGlobalLease(\n PUBLIC_CHECK_EXECUTION_LEASE_NAME,\n owner,\n renewalAt.toISOString(),\n executionLeaseUntil,\n )\n if (!hasExecutionLease) {\n // This is a transient capacity race, not a failed check. Persist it back\n // to the queue so a later request/durable trigger can safely claim it.\n return (await options.store.requeueJob(checkId, owner, now().toISOString())) ? 'busy' : 'ignored'\n }\n shouldReleaseExecutionLease = true\n\n const signal = AbortSignal.timeout(PUBLIC_CHECK_WORK_BUDGET_MS)\n const [visibilityResult, siteHealthResult] = await Promise.allSettled([\n options.visibilityProbe\n ? options.visibilityProbe.probe({\n domain: record.domain,\n userQueries: record.userQueries,\n maxPlannerCalls: 1,\n maxProbeCalls: 3,\n signal,\n })\n : Promise.reject(new Error('The AI Visibility sample is not configured yet.')),\n options.siteHealthRunner.run(record.domain, signal),\n ])\n\n const errors: CheckResult['errors'] = []\n const visibility = visibilityResult.status === 'fulfilled'\n ? sanitizeVisibility(visibilityResult.value)\n : (errors.push({\n area: 'visibility',\n code: options.visibilityProbe ? 'unavailable' : 'not-configured',\n message: publicExecutionError('visibility', visibilityResult.reason, options.visibilityProbe === null),\n }),\n null)\n const siteHealth = siteHealthResult.status === 'fulfilled'\n ? sanitizeSiteHealth(siteHealthResult.value)\n : (errors.push({\n area: 'site-health',\n code: 'unavailable',\n message: publicExecutionError('site-health', siteHealthResult.reason),\n }),\n null)\n\n if (siteHealth?.status === 'error') {\n errors.push({\n area: 'site-health',\n code: 'crawl-failed',\n message: publicExecutionError('site-health', siteHealth.error),\n })\n }\n\n const completedAt = now()\n const result: CheckResult = {\n schemaVersion: CHECK_RESULT_SCHEMA_VERSION,\n domain: record.domain,\n generatedAt: completedAt.toISOString(),\n visibility,\n siteHealth,\n errors,\n }\n const hasAnyResult = visibility !== null || (siteHealth !== null && siteHealth.status !== 'error')\n const status = !hasAnyResult\n ? 'failed'\n : errors.length > 0 || siteHealth?.status === 'partial'\n ? 'partial'\n : 'complete'\n await options.store.finalizeJob(checkId, owner, {\n status,\n updatedAt: completedAt.toISOString(),\n // Failed checks are never reused, but they still need a TTL so their\n // public capability URL and durable row do not live forever.\n expiresAt: new Date(completedAt.getTime() + options.ttlMs).toISOString(),\n result,\n errorCode: status === 'failed' ? 'check-failed' : null,\n errorMessage: status === 'failed' ? 'The public check could not complete.' : null,\n })\n return 'completed'\n } finally {\n if (shouldReleaseExecutionLease) {\n await options.store.releaseGlobalLease(PUBLIC_CHECK_EXECUTION_LEASE_NAME, owner)\n }\n }\n },\n }\n}\n\nfunction sanitizeVisibility(report: VisibilityReport): VisibilityReport {\n return {\n schemaVersion: clip(report.schemaVersion, 32),\n domain: clip(report.domain, 253),\n startedAt: report.startedAt,\n completedAt: report.completedAt,\n summary: {\n successfulChecks: finiteCount(report.summary.successfulChecks),\n failedChecks: finiteCount(report.summary.failedChecks),\n mentionRate: finiteRate(report.summary.mentionRate),\n citationRate: finiteRate(report.summary.citationRate),\n },\n evidence: report.evidence.slice(0, 3).map((evidence) => ({\n query: clip(evidence.query, 300),\n provider: clip(evidence.provider, 80),\n requestedModel: nullableClip(evidence.requestedModel, 160),\n servedModel: nullableClip(evidence.servedModel, 160),\n completedAt: evidence.completedAt,\n answerText: nullableClip(evidence.answerText, 4_000),\n mentioned: evidence.mentioned == null ? null : Boolean(evidence.mentioned),\n matchedTerms: evidence.matchedTerms.slice(0, 12).map((term) => clip(term, 160)),\n cited: evidence.cited == null ? null : Boolean(evidence.cited),\n citedDomains: evidence.citedDomains.slice(0, 12).map((domain) => clip(domain, 253)),\n citedUrls: evidence.citedUrls.slice(0, 12).map((url) => clip(url, 2_048)),\n matchedCitationDomains: evidence.matchedCitationDomains.slice(0, 12).map((domain) => clip(domain, 253)),\n matchedCitationUrls: evidence.matchedCitationUrls.slice(0, 12).map((url) => clip(url, 2_048)),\n sources: evidence.sources.slice(0, 12).map((source) => ({\n url: clip(source.url, 2_048),\n title: nullableClip(source.title, 300),\n })),\n searchQueries: evidence.searchQueries.slice(0, 12).map((query) => clip(query, 300)),\n // Already verified to be written in the answer, so these are the answer's\n // own words. Bounded anyway, like every other array on this record.\n namedBrands: evidence.namedBrands === null\n ? null\n : evidence.namedBrands.slice(0, 12).map((name) => clip(name, 64)),\n retrievalStatus: evidence.retrievalStatus,\n // Provider adapters may include transport diagnostics, so only a known\n // classification survives; anything else becomes the generic sentence.\n error: publicProbeError(evidence.error),\n })),\n }\n}\n\nfunction sanitizeSiteHealth(sample: SiteHealthSample): SiteHealthSample {\n return {\n ...sample,\n warnings: sample.warnings.slice(0, 4).map(() => 'Some optional crawl checks were unavailable.'),\n pages: sample.pages.slice(0, 5).map((page) => ({\n ...page,\n error: page.error ? 'This page could not be audited.' : null,\n })),\n error: sample.error === null ? null : publicExecutionError('site-health', sample.error),\n }\n}\n\nfunction finiteCount(value: number): number {\n return Number.isFinite(value) && value >= 0 ? Math.floor(value) : 0\n}\n\nfunction finiteRate(value: number | null): number | null {\n return value != null && Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : null\n}\n\nfunction nullableClip(value: string | null, max: number): string | null {\n return value == null ? null : clip(value, max)\n}\n\n/**\n * Why a whole PHASE could not run, as opposed to why one probe failed.\n *\n * The per-row reason was already preserved; this was not, so a visibility phase\n * that threw before producing a single row reported \"The AI Visibility sample\n * could not complete.\" and nothing else. That is the same defect one level up:\n * the reason exists at the throw site and is destroyed on the way out.\n *\n * A phase throw is a planning failure or a provider failure, and both arrive as\n * an Error whose message the classifiers below already know how to reduce to a\n * closed set. Anything they do not recognize still becomes the generic\n * sentence, so an unbounded provider message can never reach the record.\n */\nconst PUBLIC_VISIBILITY_PHASE_ERRORS = new Map([\n ['The provider rate-limited this request.', 'The answer engine rate-limited this check.'],\n ['The provider was temporarily unavailable.', 'The answer engine was temporarily unavailable.'],\n ['The provider credentials were rejected.', 'This check could not be authorized with the answer engine.'],\n ['The provider request timed out.', 'The answer engine did not respond in time.'],\n])\n\n/** Exported for the test that pins every phase failure to a public sentence. */\nexport function visibilityPhaseError(error: unknown): string {\n if (isTimeout(error)) return 'The AI Visibility sample timed out.'\n if (!(error instanceof Error)) return VISIBILITY_GENERIC_ERROR\n\n const classified = PUBLIC_VISIBILITY_PHASE_ERRORS.get(safeProviderErrorMessage(error))\n if (classified) return classified\n\n // Planning failures are the val's own strings, not a provider body, and they\n // are the difference between \"the engine is down\" and \"we could not build a\n // question set for this domain\" — which is a fact about the DOMAIN.\n if (/query planner/i.test(error.message)) {\n return 'Questions could not be generated for this domain.'\n }\n return VISIBILITY_GENERIC_ERROR\n}\n\nfunction publicExecutionError(area: 'visibility' | 'site-health', error: unknown, notConfigured = false): string {\n if (area === 'visibility' && notConfigured) return 'The AI Visibility sample is not configured for this demo.'\n if (area === 'site-health' && typeof error === 'string' && SAFE_SITE_HEALTH_ERRORS.has(error)) return error\n if (area === 'visibility') return visibilityPhaseError(error)\n return isTimeout(error) ? SITE_HEALTH_TIMEOUT_ERROR : SITE_HEALTH_GENERIC_ERROR\n}\n\nfunction isTimeout(error: unknown): boolean {\n return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')\n}\n\nfunction clip(value: string, max: number): string {\n return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`\n}\n",[],[197,461,453],"jobs","96780fc5-c060-4b02-86a2-4b51b47199f6",11,["D",1788292310414],[219],[197,461],"3f38e0a0-df02-47e0-b3d1-c0c6af1feaec","939da182-a63e-11f1-b150-1607ee4eb77e","92281dc8-a63e-11f1-8621-1607ee4eb77e",35,["D",1788292311811],"import {\n createTurnstileVerifier,\n type HumanVerifier,\n LocalBypassHumanVerifier,\n UnavailableHumanVerifier,\n} from '../security/turnstile.ts'\n\nexport interface ValTownConfig {\n environment: 'production' | 'development' | 'test'\n checkTtlMs: number\n perClientDailyLimit: number\n globalDailyLimit: number\n quotaSalt: string\n humanVerifier: HumanVerifier\n turnstileSiteKey: string | null\n humanVerificationStatus: 'ready' | 'not-required' | 'unavailable'\n geminiApiKey: string | null\n geminiModel: string | null\n publicChecksEnabled: boolean\n publicChecksUnavailableMessage: string | null\n /** Whether the MCP endpoint may start a check. Reads are always available. */\n mcpStartChecksEnabled: boolean\n /** Daily per-caller allowance for MCP-started checks, in its own quota bucket. */\n mcpPerClientDailyLimit: number\n}\n\nfunction positiveInt(input: string | undefined, fallback: number): number {\n const parsed = Number(input)\n return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback\n}\n\nfunction splitCsv(input: string | undefined): string[] {\n return (input ?? '').split(',').map((value) => value.trim()).filter(Boolean)\n}\n\n/**\n * Env parsing is intentionally small. A deployed production val refuses every\n * public check if Turnstile isn't configured; local/test can opt into the\n * explicit bypass to keep tests free of secrets.\n */\nexport function loadValTownConfig(env: Record = Deno.env.toObject()): ValTownConfig {\n // There is no trusted implicit signal that a Val is a development host.\n // Default to production so the local bypass must always be opted into with\n // both an explicit environment and its deliberately unsafe flag.\n const environment = env.VAL_TOWN_ENV === 'development'\n ? 'development'\n : env.VAL_TOWN_ENV === 'test'\n ? 'test'\n : 'production'\n const secret = env.TURNSTILE_SECRET_KEY?.trim()\n const siteKey = env.TURNSTILE_SITE_KEY?.trim()\n const allowedHostnames = splitCsv(env.TURNSTILE_ALLOWED_HOSTNAMES)\n const hasCompleteTurnstileConfig = Boolean(secret && siteKey && allowedHostnames.length > 0)\n const configuredQuotaSalt = env.CANONRY_QUOTA_SALT?.trim() || null\n\n let humanVerifier: HumanVerifier\n let humanVerificationStatus: ValTownConfig['humanVerificationStatus']\n if (hasCompleteTurnstileConfig && secret) {\n humanVerifier = createTurnstileVerifier({ secret, allowedHostnames })\n humanVerificationStatus = 'ready'\n } else if (environment !== 'production' && env.ALLOW_INSECURE_LOCAL_HUMAN_BYPASS === '1') {\n humanVerifier = new LocalBypassHumanVerifier()\n humanVerificationStatus = 'not-required'\n } else {\n humanVerifier = new UnavailableHumanVerifier()\n humanVerificationStatus = 'unavailable'\n }\n\n return {\n environment,\n checkTtlMs: positiveInt(env.CANONRY_CHECK_CACHE_TTL_MS, 86_400_000),\n perClientDailyLimit: positiveInt(env.CANONRY_PER_CLIENT_DAILY_LIMIT, 3),\n globalDailyLimit: positiveInt(env.CANONRY_GLOBAL_DAILY_LIMIT, 100),\n // A stable shared salt is required in production. A process-local fallback\n // would make per-IP quotas disappear whenever Val starts another isolate.\n quotaSalt: configuredQuotaSalt || (environment === 'production' ? '' : 'local-development-only'),\n humanVerifier,\n turnstileSiteKey: humanVerificationStatus === 'ready' ? siteKey || null : null,\n humanVerificationStatus,\n geminiApiKey: env.GEMINI_API_KEY?.trim() || null,\n geminiModel: env.GEMINI_VISIBILITY_MODEL?.trim() || null,\n publicChecksEnabled: environment !== 'production' || Boolean(configuredQuotaSalt),\n publicChecksUnavailableMessage: environment === 'production' && !configuredQuotaSalt\n ? 'Public checks are temporarily unavailable.'\n : null,\n // An agent cannot solve a Turnstile challenge, so the MCP write path trades\n // human verification for a much tighter per-caller allowance. The global\n // daily cap and the single execution lease are unchanged, so this widens\n // who may spend the budget, never how large the budget is.\n mcpStartChecksEnabled: env.CANONRY_MCP_START_CHECKS !== '0',\n mcpPerClientDailyLimit: positiveInt(env.CANONRY_MCP_PER_CLIENT_DAILY_LIMIT, 2),\n }\n}\n",[],[197,475,302],"config","5b29d0bc-67f9-4641-abd9-7035be8a9b71",["D",1788292309530],[217],[197,475],"0a2ea28c-944f-43a2-9acf-a8436f9030b8","app.ts","9349f686-a63e-11f1-b64b-1607ee4eb77e","91f8f4bc-a63e-11f1-8621-1607ee4eb77e",297,["D",1788465274410],"import { Hono } from 'npm:hono@4.12.25'\nimport type { ValTownConfig } from 'npm:@canonry/val-kit@0.1.0/config'\nimport {\n type CheckRecord,\n checkFingerprint,\n type CheckStore,\n isCheckExpired,\n type JobDispatcher,\n newCheckRecord,\n normalizeUserQueries,\n PUBLIC_CHECK_EXECUTION_LEASE_MS,\n PUBLIC_CHECK_EXECUTION_LEASE_NAME,\n PUBLIC_RATE_LIMITED_ERROR_CODE,\n} from 'npm:@canonry/val-kit@0.1.0/jobs'\nimport {\n HumanVerificationError,\n normalizePublicDomain,\n PublicUrlError,\n utcDay,\n} from 'npm:@canonry/val-kit@0.1.0/security'\nimport { PublicQuotaError } from '../jobs/public-check.ts'\nimport { createMcpHandler } from '../mcp/server.ts'\nimport { CHECK_FINGERPRINT_NAMESPACE, type CheckResult } from '../runtime/check-result.ts'\n\nconst MAX_BODY_BYTES = 4_096\nconst CHECK_ID = /^[0-9a-f-]{36}$/i\n\nexport interface PageAssets {\n styles: string\n script: string\n /** Plated logo, used as the favicon. */\n mark: string\n /** Bare glyph, used inline in the brand lockup. */\n glyph: string\n}\n\nexport interface ValTownAppDependencies {\n store: CheckStore\n config: ValTownConfig\n dispatcher: JobDispatcher\n /** The UI is injected so this host stays independent from the renderer implementation. */\n renderPage: (record: CheckRecord | null) => string\n assets: PageAssets\n now?: () => Date\n}\n\nexport class PublicCheckUnavailableError extends Error {\n override name = 'PublicCheckUnavailableError'\n}\n\nclass PublicCheckAdmissionBusyError extends Error {\n override name = 'PublicCheckAdmissionBusyError'\n constructor() {\n super('Another request for this domain is being accepted. Try again shortly.')\n }\n}\n\nclass PublicCheckCapacityError extends Error {\n override name = 'PublicCheckCapacityError'\n constructor() {\n super('The public check is at capacity. Try again shortly.')\n }\n}\n\nexport function createValTownApp(deps: ValTownAppDependencies): Hono {\n const app = new Hono()\n const now = deps.now ?? (() => new Date())\n\n app.use('*', async (context, next) => {\n const turnstileAllowed = deps.config.publicChecksEnabled &&\n deps.config.humanVerificationStatus === 'ready' && Boolean(deps.config.turnstileSiteKey)\n context.header('Content-Security-Policy', contentSecurityPolicy(turnstileAllowed))\n context.header('X-Content-Type-Options', 'nosniff')\n context.header('Referrer-Policy', 'strict-origin-when-cross-origin')\n context.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()')\n context.header('Cross-Origin-Opener-Policy', 'same-origin')\n await next()\n })\n\n app.get('/healthz', (context) => context.json({ ok: true }))\n\n // Anonymous, read-only MCP over Streamable HTTP. It shares this app's store\n // so an agent reads exactly the checks the UI shows, and it owns its own\n // method/origin/envelope handling — including the 405 for a non-POST, which\n // is why it is registered for every method rather than POST alone.\n const mcp = createMcpHandler({\n store: deps.store,\n now,\n startCheck: deps.config.mcpStartChecksEnabled\n ? async (domain, remoteIp, queries) => {\n const outcome = await submitCheck(deps, {\n domain,\n queries,\n token: null,\n remoteIp,\n now: now(),\n admission: 'mcp',\n })\n return { record: (await deps.store.get(outcome.record.id)) ?? outcome.record, reused: outcome.reused }\n }\n : undefined,\n })\n app.all('/mcp', (context) => mcp(context.req.raw))\n // Immutable: the document references these with a content hash, so a changed\n // asset arrives under a new URL rather than waiting out a TTL.\n app.get('/assets/canonry-ui.css', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.styles, 200, { 'content-type': 'text/css; charset=utf-8' })\n })\n app.get('/assets/canonry-ui.js', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.script, 200, { 'content-type': 'application/javascript; charset=utf-8' })\n })\n app.get('/assets/canonry-mark.svg', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.mark, 200, { 'content-type': 'image/svg+xml; charset=utf-8' })\n })\n app.get('/assets/canonry-glyph.svg', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.glyph, 200, { 'content-type': 'image/svg+xml; charset=utf-8' })\n })\n\n app.get('/', async (context) => {\n const requestedId = context.req.query('check')\n const stored = requestedId && CHECK_ID.test(requestedId) ? await deps.store.get(requestedId) : null\n const record = stored && !isCheckExpired(stored, now()) ? stored : null\n context.header('Cache-Control', 'no-store')\n return context.html(deps.renderPage(record))\n })\n\n app.get('/api/checks/:id', async (context) => {\n const id = context.req.param('id')\n if (!CHECK_ID.test(id)) return apiError(context, 404, 'not-found', 'Check not found.')\n const record = await deps.store.get(id)\n if (!record || isCheckExpired(record, now())) return apiError(context, 404, 'not-found', 'Check not found.')\n context.header('Cache-Control', 'no-store')\n return context.json({ check: publicCheckRecord(record) })\n })\n\n app.post('/api/checks', async (context) => {\n const payload = await parseJsonBody(context.req.raw)\n const outcome = await submitCheck(deps, {\n domain: payload.domain,\n queries: payload.queries,\n token: typeof payload.turnstileToken === 'string' ? payload.turnstileToken : null,\n remoteIp: remoteIp(context.req.raw),\n now: now(),\n })\n context.header('Cache-Control', 'no-store')\n if (outcome.dispatch === 'busy') {\n return apiError(context, 503, 'busy', 'The public check is at capacity. Try again shortly.')\n }\n return context.json(\n { check: publicCheckRecord(outcome.record), reused: outcome.reused },\n outcome.record.status === 'queued' || outcome.record.status === 'running' ? 202 : 200,\n )\n })\n\n app.post('/check', async (context) => {\n let submittedDomain: unknown = null\n try {\n const form = await parseFormBody(context.req.raw)\n submittedDomain = form.get('domain')\n const outcome = await submitCheck(deps, {\n domain: submittedDomain,\n queries: form.get('queries'),\n token: form.get('cf-turnstile-response'),\n remoteIp: remoteIp(context.req.raw),\n now: now(),\n })\n if (outcome.dispatch === 'busy') throw new PublicCheckCapacityError()\n return context.redirect(`/?check=${encodeURIComponent(outcome.record.id)}`, 303)\n } catch (error) {\n const failure = formFailureRecord(submittedDomain, now(), error)\n context.header('Cache-Control', 'no-store')\n return context.html(deps.renderPage(failure), formFailureStatus(error))\n }\n })\n\n app.notFound((context) => apiError(context, 404, 'not-found', 'Not found.'))\n app.onError((error, context) => {\n if (error instanceof PublicUrlError) return apiError(context, 400, 'invalid-domain', error.message)\n if (error instanceof HumanVerificationError) {\n const status = error.code === 'unavailable' || error.code === 'transport' ? 503 : 403\n return apiError(context, status, `human-verification-${error.code}`, error.message)\n }\n if (error instanceof PublicQuotaError) return apiError(context, 429, `${error.scope}-quota`, error.message)\n if (error instanceof PublicCheckAdmissionBusyError) return apiError(context, 503, 'admission-busy', error.message)\n if (error instanceof PublicCheckCapacityError) return apiError(context, 503, 'busy', error.message)\n if (error instanceof PublicCheckUnavailableError) return apiError(context, 503, 'unavailable', error.message)\n if (error instanceof BodyTooLargeError) {\n return apiError(context, 413, 'body-too-large', 'Request body is too large.')\n }\n if (error instanceof InvalidBodyError) return apiError(context, 400, 'invalid-body', error.message)\n return apiError(context, 500, 'internal-error', 'The public check could not be started.')\n })\n\n return app\n}\n\ninterface SubmitInput {\n domain: unknown\n /** Raw caller input; normalized here, never trusted as given. */\n queries?: unknown\n token: string | null\n remoteIp: string | null\n now: Date\n /**\n * Which admission rules apply. `mcp` skips human verification, which an\n * agent cannot perform, and spends from a separate, tighter daily bucket so\n * it cannot consume the browser allowance. Every other control — the global\n * daily cap, the single execution lease, cache reuse — is identical.\n */\n admission?: 'browser' | 'mcp'\n}\n\nasync function submitCheck(\n deps: ValTownAppDependencies,\n input: SubmitInput,\n): Promise<{ record: CheckRecord; reused: boolean; dispatch: 'completed' | 'busy' | 'ignored' }> {\n if (!deps.config.publicChecksEnabled) {\n throw new PublicCheckUnavailableError(\n deps.config.publicChecksUnavailableMessage ?? 'Public checks are temporarily unavailable.',\n )\n }\n const target = normalizePublicDomain(input.domain)\n const userQueries = normalizeUserQueries(input.queries)\n const viaMcp = input.admission === 'mcp'\n if (!viaMcp) await deps.config.humanVerifier.verify({ token: input.token, remoteIp: input.remoteIp })\n // The questions join the reuse key. They change what the check measures, so\n // a second caller asking different questions about the same domain must not\n // be handed the first caller's answers.\n const fingerprint = checkFingerprint(CHECK_FINGERPRINT_NAMESPACE, target.domain, userQueries)\n const timestamp = input.now.toISOString()\n\n // Cached and already-active work is useful without consuming the one global\n // execution slot. This keeps same-domain retries quota- and capacity-free.\n const reusable = await deps.store.findReusable(fingerprint, timestamp)\n if (reusable) return dispatchExistingCheck(deps, reusable)\n\n const hashedClient = await hashQuotaSubject(deps.config.quotaSalt, input.remoteIp ?? 'unknown')\n // A distinct subject rather than a distinct scope: `CheckQuotaClaim.scope` is\n // a closed union, and prefixing keeps the two buckets disjoint without\n // widening a durable contract.\n const clientSubject = viaMcp ? `mcp:${hashedClient}` : hashedClient\n const clientMax = viaMcp ? deps.config.mcpPerClientDailyLimit : deps.config.perClientDailyLimit\n const day = utcDay(input.now)\n const executionLeaseOwner = crypto.randomUUID()\n const executionLeaseUntil = new Date(input.now.getTime() + PUBLIC_CHECK_EXECUTION_LEASE_MS).toISOString()\n const capacityAvailable = await deps.store.claimGlobalLease(\n PUBLIC_CHECK_EXECUTION_LEASE_NAME,\n executionLeaseOwner,\n timestamp,\n executionLeaseUntil,\n )\n if (!capacityAvailable) throw new PublicCheckCapacityError()\n\n let capacityHeld = true\n let dispatchOwnsCapacity = false\n const releaseCapacity = async () => {\n if (!capacityHeld) return\n await deps.store.releaseGlobalLease(PUBLIC_CHECK_EXECUTION_LEASE_NAME, executionLeaseOwner)\n capacityHeld = false\n }\n\n try {\n const admission = await deps.store.admit({\n candidate: newCheckRecord({\n id: crypto.randomUUID(),\n fingerprint,\n domain: target.domain,\n userQueries,\n now: input.now,\n }),\n now: timestamp,\n clientQuota: { scope: 'client', subject: clientSubject, day, max: clientMax },\n globalQuota: { scope: 'global', subject: 'all', day, max: deps.config.globalDailyLimit },\n })\n if (admission.kind === 'quota-exhausted') throw new PublicQuotaError(admission.scope)\n if (admission.kind === 'busy') throw new PublicCheckAdmissionBusyError()\n\n if (admission.kind === 'reused') {\n // A concurrent same-domain admission won. It must not inherit capacity\n // reserved by this request, so it goes through ordinary reuse dispatch.\n await releaseCapacity()\n return dispatchExistingCheck(deps, admission.record)\n }\n\n let dispatch: 'completed' | 'busy' | 'ignored' = 'ignored'\n if (admission.record.status === 'queued') {\n // Request-bound dispatch takes responsibility for this owner as soon as\n // it receives the promise. Its runner releases even a lost job claim.\n const dispatched = deps.dispatcher.dispatch(admission.record.id, { executionLeaseOwner })\n dispatchOwnsCapacity = true\n dispatch = await dispatched\n }\n return {\n record: (await deps.store.get(admission.record.id)) ?? admission.record,\n reused: admission.kind !== 'created',\n dispatch,\n }\n } finally {\n // The runner owns capacity only after dispatch receives the owner. The app\n // releases every admission, reuse, quota, and pre-dispatch error path.\n if (!dispatchOwnsCapacity) await releaseCapacity()\n }\n}\n\nasync function dispatchExistingCheck(\n deps: ValTownAppDependencies,\n record: CheckRecord,\n): Promise<{ record: CheckRecord; reused: true; dispatch: 'completed' | 'busy' | 'ignored' }> {\n const dispatch = record.status === 'queued' ? await deps.dispatcher.dispatch(record.id) : 'ignored'\n return {\n record: (await deps.store.get(record.id)) ?? record,\n reused: true,\n dispatch,\n }\n}\n\nfunction publicCheckRecord(\n record: CheckRecord,\n): Omit, 'fingerprint' | 'leaseOwner' | 'leaseUntil'> {\n const { fingerprint: _fingerprint, leaseOwner: _leaseOwner, leaseUntil: _leaseUntil, ...safe } = record\n return safe\n}\n\nfunction apiError(\n context: { json: (body: unknown, status?: number) => Response; header: (name: string, value: string) => void },\n status: number,\n code: string,\n message: string,\n): Response {\n context.header('Cache-Control', 'no-store')\n return context.json({ error: { code, message } }, status)\n}\n\nclass BodyTooLargeError extends Error {}\nclass InvalidBodyError extends Error {}\n\nasync function parseJsonBody(request: Request): Promise> {\n if (!request.headers.get('content-type')?.toLowerCase().includes('application/json')) {\n throw new InvalidBodyError('Expected a JSON request body.')\n }\n const text = await readLimitedBody(request)\n try {\n const parsed = JSON.parse(text)\n if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error()\n return parsed as Record\n } catch {\n throw new InvalidBodyError('Request body must be a JSON object.')\n }\n}\n\nasync function parseFormBody(request: Request): Promise {\n if (!request.headers.get('content-type')?.toLowerCase().includes('application/x-www-form-urlencoded')) {\n throw new InvalidBodyError('Expected a form submission.')\n }\n return new URLSearchParams(await readLimitedBody(request))\n}\n\nasync function readLimitedBody(request: Request): Promise {\n const contentLength = Number(request.headers.get('content-length'))\n if (Number.isFinite(contentLength) && contentLength > MAX_BODY_BYTES) throw new BodyTooLargeError()\n if (!request.body) return ''\n const reader = request.body.getReader()\n const chunks: Uint8Array[] = []\n let length = 0\n while (true) {\n const next = await reader.read()\n if (next.done) break\n length += next.value.byteLength\n if (length > MAX_BODY_BYTES) {\n await reader.cancel()\n throw new BodyTooLargeError()\n }\n chunks.push(next.value)\n }\n const output = new Uint8Array(length)\n let offset = 0\n for (const chunk of chunks) {\n output.set(chunk, offset)\n offset += chunk.byteLength\n }\n return new TextDecoder().decode(output)\n}\n\nfunction remoteIp(request: Request): string | null {\n // Val injects this edge header. `x-forwarded-for` is caller-controlled on a\n // public val, so it is deliberately ignored for quota identity.\n const cf = request.headers.get('cf-connecting-ip')?.trim()\n if (cf && cf.length <= 128) return cf\n return null\n}\n\nasync function hashQuotaSubject(salt: string, value: string): Promise {\n const bytes = new TextEncoder().encode(`${salt}\\u0000${value}`)\n const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))\n return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('')\n}\n\n/**\n * `frame-ancestors` allows Val Town because the val's own page previews the\n * deployed site in an iframe, and `'none'` renders that preview blank — the\n * first thing anyone arriving from val.town sees. The allowance is exactly the\n * hosting platform and nothing else, so ordinary clickjacking is still blocked.\n * There is little to hijack regardless: no session, no credential, and the only\n * action is submitting a public domain.\n */\nconst FRAME_ANCESTORS = [\"'self'\", 'https://www.val.town', 'https://val.town'].join(' ')\n\n/**\n * Geist is served from jsDelivr because a Val cannot ship the font itself:\n * woff2 is binary and Val Town refuses to push binary files. It is the same\n * package and version the dashboard bundles (`@fontsource-variable/geist`), so\n * the two surfaces render in the same typeface rather than this one silently\n * falling back to a system font, which is what it did before.\n */\nconst FONT_CDN = 'https://cdn.jsdelivr.net'\n\nfunction contentSecurityPolicy(turnstileAllowed: boolean): string {\n const turnstile = turnstileAllowed ? ' https://challenges.cloudflare.com' : ''\n return [\n \"default-src 'self'\",\n \"base-uri 'none'\",\n \"object-src 'none'\",\n `frame-ancestors ${FRAME_ANCESTORS}`,\n \"form-action 'self'\",\n `script-src 'self'${turnstile}`,\n `style-src 'self' ${FONT_CDN}`,\n `font-src ${FONT_CDN}`,\n `connect-src 'self'${turnstile}`,\n `frame-src${turnstile || \" 'none'\"}`,\n \"img-src 'self' data: https:\",\n ].join('; ')\n}\n\nfunction formFailureRecord(domain: unknown, now: Date, error: unknown): CheckRecord {\n const displayDomain = typeof domain === 'string' ? domain.trim().slice(0, 253) : ''\n const timestamp = now.toISOString()\n return {\n id: crypto.randomUUID(),\n fingerprint: '',\n domain: displayDomain,\n userQueries: [],\n status: 'failed',\n createdAt: timestamp,\n updatedAt: timestamp,\n expiresAt: null,\n result: null,\n errorCode: error instanceof PublicQuotaError ? PUBLIC_RATE_LIMITED_ERROR_CODE : 'form-submission-failed',\n errorMessage: formFailureMessage(error),\n leaseOwner: null,\n leaseUntil: null,\n }\n}\n\nfunction formFailureMessage(error: unknown): string {\n if (\n error instanceof PublicUrlError || error instanceof PublicQuotaError || error instanceof HumanVerificationError ||\n error instanceof PublicCheckUnavailableError || error instanceof PublicCheckAdmissionBusyError ||\n error instanceof PublicCheckCapacityError\n ) return error.message\n if (error instanceof BodyTooLargeError) return 'The submission was too large. Enter only a domain.'\n if (error instanceof InvalidBodyError) return 'The form could not be read. Try again.'\n return 'The public check could not be started. Try again later.'\n}\n\nfunction formFailureStatus(error: unknown): 400 | 403 | 413 | 429 | 503 {\n if (error instanceof PublicUrlError || error instanceof InvalidBodyError) return 400\n if (error instanceof BodyTooLargeError) return 413\n if (error instanceof PublicQuotaError) return 429\n if (\n error instanceof PublicCheckUnavailableError || error instanceof PublicCheckAdmissionBusyError ||\n error instanceof PublicCheckCapacityError\n ) return 503\n if (error instanceof HumanVerificationError) return error.code === 'invalid' ? 403 : 503\n return 503\n}\n",[],[197,489,481],"app","099c2e2e-a5d0-494f-ae81-754dd43458ad",["D",1788292309199],[215],[197,489],["D",1788292308897],[214,216,218,220,225,228,233,235],[197],["D",1788292195151],["D",1789514495229],{"_100":99,"_108":104},{"_100":99,"_101":102,"_103":104,"_18":-5,"_105":106,"_107":48},{"_13":89,"_32":90,"_42":41,"_91":43,"_92":-5,"_93":-5,"_94":-5,"_95":-5,"_96":-5,"_97":44,"_98":99},"ctx",{"_82":-5,"_128":535,"_536":537,"_538":539,"_540":48,"_541":48,"_542":48,"_543":25,"_544":-5,"_545":-7,"_546":-7,"_547":63,"_548":48,"_549":48,"_550":-5,"_551":48,"_552":48,"_553":48,"_554":-5},"ENV",{"_506":507,"_508":509,"_510":90,"_511":512,"_513":514,"_515":516,"_517":518,"_519":520,"_521":522,"_523":524,"_525":526,"_527":528,"_529":530,"_531":532,"_533":534},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Who else shows up

Answer-engine snapshot

Query evidence

Evidence

Recommended fix

Technical AEO sample

${escapeHtml(siteHealth.sampleLabel)}

Problems outside the score

Factors

Worst sampled pages

Does AI mention your brand?${renderInfoTip(LANDING_EXPLAINER)}

${escapeHtml(model.domain)}

Diff · v310