@nebulacomponents/citable 1.18.2 → 1.20.0

package/src/detectors/tech.js

@@ -5,6 +5,7 @@ import { isAllowed } from '../crawler/robots.js';
 const D = [];
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-001', name: 'Non-200 index-target URL', namespace: 'TECH',
   description: 'A page intended for indexing does not return HTTP 200.',
   discipline: ['seo', 'aeo', 'geo'], severity: 'critical', deterministic: true, requires: ['site'],
@@ -23,6 +24,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-002', name: 'Accidental noindex on index-target page', namespace: 'TECH',
   description: 'A page whose registry intent is "index" carries a noindex directive (meta robots or X-Robots-Tag).',
   discipline: ['seo', 'aeo', 'geo'], severity: 'critical', deterministic: true, requires: ['site'],
@@ -41,6 +43,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-003', name: 'robots.txt blocks index-target page', namespace: 'TECH',
   description: 'robots.txt disallows a search crawler from fetching a page that is intended to be indexed and cited.',
   discipline: ['seo', 'aeo', 'geo'], severity: 'critical', deterministic: true, requires: ['site'],
@@ -67,6 +70,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-004', name: 'Multiple conflicting canonical declarations', namespace: 'TECH',
   description: 'A document declares more than one rel=canonical with differing targets.',
   discipline: ['seo', 'aeo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -85,6 +89,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-005', name: 'Canonical points to redirect', namespace: 'TECH',
   description: 'rel=canonical targets a URL that itself redirects.',
   discipline: ['seo', 'aeo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -98,6 +103,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-006', name: 'Canonical points to error page', namespace: 'TECH',
   description: 'rel=canonical targets a URL returning 4xx/5xx.',
   discipline: ['seo', 'aeo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -111,6 +117,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-007', name: 'Canonical points to noindex page', namespace: 'TECH',
   description: 'rel=canonical consolidates signals into a URL that is itself noindexed.',
   discipline: ['seo', 'aeo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -124,6 +131,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-008', name: 'Sitemap contains redirecting URL', namespace: 'TECH',
   description: 'An XML sitemap lists a URL that does not resolve directly with HTTP 200 (redirects).',
   discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
@@ -137,6 +145,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-009', name: 'Sitemap contains non-canonical URL', namespace: 'TECH',
   description: 'A sitemap lists a URL whose page declares a different canonical.',
   discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
@@ -166,6 +175,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-010', name: 'Sitemap URL unresolvable or errors', namespace: 'TECH',
   description: 'A sitemap lists a URL that is missing from the built output or returns an error.',
   discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
@@ -178,13 +188,19 @@ D.push(defineDetector({
     for (const sm of ctx.site.sitemaps) {
       for (const u of sm.parsed.urls) {
         const page = ctx.site.byUrl.get(ctx.site.normalize(u.loc));
-        if (!page && ctx.site.mode === 'url' && ctx.site.crawl?.truncated) {
+        const crawlState = ctx.site.mode === 'url' ? ctx.site.coverageLedger?.stateFor(u.loc) : null;
+        if (!page && ctx.site.mode === 'url' && crawlState !== 'failed') {
+          // An unvisited or merely queued sitemap URL is not evidence of an
+          // invalid resource. Coverage records it for an aggregate
+          // determination instead of manufacturing a TECH-010 absence claim.
           continue;
         } else if (!page) {
           hits.push({
             subject: { type: 'url', identifier: u.loc, url: u.loc, source_location: sm.source },
-            summary: 'Sitemap URL not present in audited output',
-            evidence: [`sitemap ${sm.source} lists ${u.loc}; no matching page found`],
+            summary: crawlState === 'failed' ? 'Sitemap URL fetch failed' : 'Sitemap URL not present in audited output',
+            evidence: [crawlState === 'failed'
+              ? `sitemap ${sm.source} lists ${u.loc}; retrieval failed after attempted observation`
+              : `sitemap ${sm.source} lists ${u.loc}; no matching page found`],
           });
         } else if (page.status >= 400) {
           hits.push({
@@ -200,6 +216,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-011', name: 'Render-dependent primary content', namespace: 'TECH',
   description: 'Initial HTML contains almost no primary text relative to script payload; principal content likely requires client-side rendering.',
   discipline: ['seo', 'aeo', 'geo'], severity: 'high', deterministic: false, requires: ['site'],
@@ -221,6 +238,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-012', name: 'Invalid MIME type for HTML page', namespace: 'TECH',
   description: 'An index-target page is served with a non-HTML content type.',
   discipline: ['seo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -241,6 +259,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-013', name: 'Redirect chain', namespace: 'TECH',
   description: 'Reaching the final URL required more than one redirect hop.',
   discipline: ['seo'], severity: 'medium', deterministic: true, requires: ['site'],
@@ -258,6 +277,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-014', name: 'Soft-404 behaviour', namespace: 'TECH',
   description: 'A page returns 200 but its content indicates the resource does not exist.',
   discipline: ['seo'], severity: 'medium', deterministic: false, requires: ['site'],
@@ -280,6 +300,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-015', name: 'Staging or preview host exposed as indexable', namespace: 'TECH',
   description: 'The audited base URL looks like a staging/preview environment yet pages are indexable.',
   discipline: ['seo'], severity: 'critical', deterministic: false, requires: ['site'],
@@ -305,6 +326,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'exhaustive_requested_scope',
   id: 'TECH-016', name: 'Missing sitemap', namespace: 'TECH',
   description: 'No XML sitemap was found for the audited output.',
   discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
@@ -323,6 +345,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-017', name: 'Snippet suppression on citation-target page', namespace: 'TECH',
   description: 'A page targeted for answer citation carries nosnippet or max-snippet:0, which removes snippet eligibility that generative search features depend on.',
   discipline: ['aeo', 'geo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -340,6 +363,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-018', name: 'Missing viewport (mobile readiness)', namespace: 'TECH',
   description: 'Page lacks a viewport meta tag, a minimum condition for mobile parity.',
   discipline: ['seo'], severity: 'low', deterministic: true, requires: ['site'],
@@ -360,6 +384,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-019', name: 'Open Graph URL conflicts with canonical', namespace: 'TECH',
   description: 'Open Graph URL (og:url) disagrees with the declared canonical URL, sending conflicting canonicalization and entity identity signals.',
   discipline: ['seo', 'aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['site'],
@@ -395,6 +420,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-020', name: 'Missing reciprocal hreflang return link', namespace: 'TECH',
   description: 'An alternate hreflang URL targets an internal page, but that target page does not reciprocate with a matching hreflang link back to the source page.',
   discipline: ['seo', 'geo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -445,6 +471,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-021', name: 'Invalid or non-standard BCP 47 hreflang syntax', namespace: 'TECH',
   description: 'An hreflang annotation uses an invalid language code, malformed region subtag, deprecated territory, or relative URL.',
   discipline: ['seo', 'geo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -493,6 +520,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-022', name: 'Hreflang alternate target conflicts with rel=canonical', namespace: 'TECH',
   description: 'An alternate hreflang URL points to a page that declares a different rel=canonical target, breaking the alternate cluster.',
   discipline: ['seo', 'geo'], severity: 'critical', deterministic: true, requires: ['site'],
@@ -539,6 +567,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-023', name: 'Hydration gap: critical metadata or schema missing from initial server HTML response', namespace: 'TECH',
   description: 'A single-page application or client-rendered document returns empty content mounting shells with virtually no static text (<20 words) in initial server HTML, breaking crawler and answer engine extraction without full headless JS rendering.',
   discipline: ['seo', 'aeo'], severity: 'high', deterministic: true, requires: ['site'],
@@ -574,6 +603,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-024', name: 'Excessive render-blocking script payload exceeding crawler execution budget', namespace: 'TECH',
   description: 'The page delivers excessive inline/head script payloads (>1.2MB) or an excessive number of render-blocking head scripts (>12 without defer/async), exhausting crawler execution budgets and delaying indexing.',
   discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
@@ -619,6 +649,7 @@ D.push(defineDetector({
 }));
 
 D.push(defineDetector({
+  coverage_requirement: 'evaluated_subset',
   id: 'TECH-025', name: 'Oversized uncompressed image asset or heavy inline image payload', namespace: 'TECH',
   description: 'The page embeds an excessively large inline image data URI (>100KB) or references raw uncompressed image payloads exceeding 1MB, delaying Largest Contentful Paint (LCP) and exhausting mobile data budgets.',
   discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],

package/src/evidence/coverage.js

@@ -0,0 +1,448 @@
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+export const COVERAGE_SCHEMA_VERSION = 1;
+
+const STOP_REASONS = new Set([
+  'frontier_exhausted',
+  'page_budget_exhausted',
+  'time_budget_exhausted',
+  'fatal_collection_failure',
+]);
+
+const DISCOVERY_STATUSES = new Set(['complete', 'truncated', 'indeterminate']);
+const TERMINAL_STATES = new Set([
+  'evaluated',
+  'valid_but_unevaluated',
+  'failed',
+  'indeterminate',
+]);
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+}
+
+function assertIntegerInRange(value, name, minimum, maximum) {
+  if (!Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new RangeError(`${name} must be an integer from ${minimum} through ${maximum}`);
+  }
+}
+
+function assertUrl(value, name) {
+  assertNonEmptyString(value, name);
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new TypeError(`${name} must be an absolute URL`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new TypeError(`${name} must use http or https`);
+  }
+  return parsed;
+}
+
+function normalizedUrl(url) {
+  assertUrl(url, 'url');
+  const fragmentIndex = url.indexOf('#');
+  return fragmentIndex === -1 ? url : url.slice(0, fragmentIndex);
+}
+
+function canonicalValue(value, path = 'metadata') {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (Array.isArray(value)) return value.map((item, index) => canonicalValue(item, `${path}[${index}]`));
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalValue(value[key], `${path}.${key}`)]),
+    );
+  }
+  throw new TypeError(`${path} must contain only JSON-compatible values`);
+}
+
+function canonicalMetadata(metadata, name) {
+  if (metadata === undefined) return {};
+  if (metadata === null || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+  return canonicalValue(metadata, name);
+}
+
+function stableString(value) {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function compareStrings(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function sortedUniqueStrings(values, name) {
+  if (!Array.isArray(values)) throw new TypeError(`${name} must be an array`);
+  for (const value of values) assertNonEmptyString(value, `${name} entry`);
+  return [...new Set(values)].sort(compareStrings);
+}
+
+function stateOf(resource) {
+  if (resource.exclusion) return 'excluded';
+  if (resource.evaluation) return 'evaluated';
+  if (resource.validButUnevaluated) return 'valid_but_unevaluated';
+  if (resource.failure) return 'failed';
+  if (resource.indeterminate) return 'indeterminate';
+  if (resource.classification?.state === 'valid_resource') return 'valid_resource';
+  if (resource.retrieval) return 'retrieved';
+  if (resource.attemptHistory.length > 0) return 'attempted';
+  return 'eligible';
+}
+
+function assertNotTerminal(resource, operation) {
+  const state = stateOf(resource);
+  if (TERMINAL_STATES.has(state) || state === 'excluded') {
+    throw new Error(`cannot ${operation} resource in terminal state ${state}`);
+  }
+}
+
+function equationError(label, left, right) {
+  return `${label} (${left} != ${right})`;
+}
+
+export function reconcileCoverage(coverage) {
+  const populations = coverage?.populations;
+  if (!populations || typeof populations !== 'object') {
+    return { valid: false, errors: ['coverage populations are missing'] };
+  }
+
+  const errors = [];
+  const discoveredParts = populations.excluded + populations.eligible;
+  if (populations.discovered !== discoveredParts) {
+    errors.push(equationError('discovered = excluded + eligible', populations.discovered, discoveredParts));
+  }
+
+  const eligibleParts = populations.evaluated
+    + populations.valid_but_unevaluated
+    + populations.failed
+    + populations.indeterminate
+    + populations.unvisited;
+  if (populations.eligible !== eligibleParts) {
+    errors.push(equationError(
+      'eligible = evaluated + valid_but_unevaluated + failed + indeterminate + unvisited',
+      populations.eligible,
+      eligibleParts,
+    ));
+  }
+
+  const attemptedParts = populations.retrieved + populations.failed;
+  if (populations.attempted !== attemptedParts) {
+    errors.push(equationError('attempted = retrieved + failed', populations.attempted, attemptedParts));
+  }
+
+  const retrievedParts = populations.valid_resource + populations.indeterminate;
+  if (populations.retrieved !== retrievedParts) {
+    errors.push(equationError('retrieved = valid_resource + indeterminate', populations.retrieved, retrievedParts));
+  }
+
+  const validResourceParts = populations.evaluated + populations.valid_but_unevaluated;
+  if (populations.valid_resource !== validResourceParts) {
+    errors.push(equationError(
+      'valid_resource = evaluated + valid_but_unevaluated',
+      populations.valid_resource,
+      validResourceParts,
+    ));
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function coverageStatusFor({ stopReason, discoveryStatus = 'complete', populations }) {
+  if (!STOP_REASONS.has(stopReason)) throw new Error(`unknown stop reason: ${stopReason}`);
+  if (!DISCOVERY_STATUSES.has(discoveryStatus)) {
+    throw new Error(`unknown discovery status: ${discoveryStatus}`);
+  }
+
+  if (stopReason === 'page_budget_exhausted' || stopReason === 'time_budget_exhausted') {
+    return 'truncated';
+  }
+  if (stopReason === 'fatal_collection_failure') return 'indeterminate';
+
+  const incomplete = populations.failed
+    + populations.indeterminate
+    + populations.valid_but_unevaluated
+    + populations.unvisited;
+  return discoveryStatus === 'complete' && incomplete === 0 ? 'complete' : 'indeterminate';
+}
+
+export function createCoverageLedger({
+  startUrl,
+  maxPages,
+  timeBudgetSeconds,
+  normalizationVersion = 'url-identity-v1',
+}) {
+  const parsedStartUrl = assertUrl(startUrl, 'startUrl');
+  assertIntegerInRange(maxPages, 'maxPages', 1, 10000);
+  assertIntegerInRange(timeBudgetSeconds, 'timeBudgetSeconds', 1, 86400);
+  assertNonEmptyString(normalizationVersion, 'normalizationVersion');
+
+  const resources = new Map();
+  let finalized = false;
+
+  function assertMutable() {
+    if (finalized) throw new Error('coverage ledger is already finalized');
+  }
+
+  function requireResource(url) {
+    const normalized = normalizedUrl(url);
+    const resource = resources.get(normalized);
+    if (!resource) throw new Error(`resource must be discovered before transition: ${url}`);
+    return resource;
+  }
+
+  function discover(url, source, metadata = {}) {
+    assertMutable();
+    const normalized = normalizedUrl(url);
+    assertNonEmptyString(source, 'source');
+    const canonical = canonicalMetadata(metadata, 'discovery metadata');
+    let resource = resources.get(normalized);
+    if (!resource) {
+      resource = {
+        normalizedUrl: normalized,
+        originalUrls: new Set(),
+        discoverySources: new Map(),
+        exclusion: null,
+        attemptHistory: [],
+        retrieval: null,
+        classification: null,
+        evaluation: null,
+        failure: null,
+        indeterminate: null,
+        validButUnevaluated: null,
+      };
+      resources.set(normalized, resource);
+    }
+    resource.originalUrls.add(url);
+    const discovery = { source, url, ...(Object.keys(canonical).length > 0 ? { metadata: canonical } : {}) };
+    resource.discoverySources.set(stableString(discovery), discovery);
+    return normalized;
+  }
+
+  function exclude(url, reason) {
+    assertMutable();
+    assertNonEmptyString(reason, 'exclusion reason');
+    const resource = requireResource(url);
+    if (resource.attemptHistory.length > 0) throw new Error('cannot exclude a resource after an attempt');
+    if (resource.exclusion) throw new Error('resource is already excluded');
+    resource.exclusion = { reason };
+  }
+
+  function attempt(url, attemptMetadata = {}) {
+    assertMutable();
+    const resource = requireResource(url);
+    assertNotTerminal(resource, 'attempt');
+    if (resource.retrieval) throw new Error('cannot attempt a resource after retrieval');
+    resource.attemptHistory.push(canonicalMetadata(attemptMetadata, 'attempt metadata'));
+  }
+
+  function retrieve(url, responseMetadata = {}) {
+    assertMutable();
+    const resource = requireResource(url);
+    assertNotTerminal(resource, 'retrieve');
+    if (resource.attemptHistory.length === 0) throw new Error('resource must have an attempt before retrieval');
+    if (resource.retrieval) throw new Error('resource is already retrieved');
+    resource.retrieval = canonicalMetadata(responseMetadata, 'response metadata');
+  }
+
+  function classify(url, classification) {
+    assertMutable();
+    const resource = requireResource(url);
+    assertNotTerminal(resource, 'classify');
+    if (!resource.retrieval) throw new Error('resource must be retrieved before classification');
+    if (resource.classification) throw new Error('resource is already classified');
+
+    const canonical = typeof classification === 'string'
+      ? { state: classification }
+      : canonicalMetadata(classification, 'classification');
+    if (canonical.state !== 'valid_resource' && canonical.state !== 'indeterminate') {
+      throw new Error('classification state must be valid_resource or indeterminate');
+    }
+    if (canonical.state === 'indeterminate') {
+      resource.indeterminate = canonical;
+    } else {
+      resource.classification = canonical;
+    }
+  }
+
+  function evaluate(url, evaluationMetadata = {}) {
+    assertMutable();
+    const resource = requireResource(url);
+    assertNotTerminal(resource, 'evaluate');
+    if (resource.classification?.state !== 'valid_resource') {
+      throw new Error('resource must be classified as a valid resource before evaluation');
+    }
+    resource.evaluation = canonicalMetadata(evaluationMetadata, 'evaluation metadata');
+  }
+
+  function fail(url, failureMetadata = {}) {
+    assertMutable();
+    const resource = requireResource(url);
+    assertNotTerminal(resource, 'fail');
+    if (resource.attemptHistory.length === 0) throw new Error('resource must have an attempt before failure');
+    if (resource.retrieval) throw new Error('retrieved resources cannot enter retrieval failure');
+    resource.failure = canonicalMetadata(failureMetadata, 'failure metadata');
+  }
+
+  function markIndeterminate(url, metadata = {}) {
+    assertMutable();
+    const resource = requireResource(url);
+    assertNotTerminal(resource, 'mark indeterminate');
+    if (!resource.retrieval) throw new Error('resource must be retrieved before it can be indeterminate');
+    if (resource.classification?.state === 'valid_resource') {
+      throw new Error('a valid resource must be evaluated or marked valid-but-unevaluated');
+    }
+    resource.indeterminate = { ...canonicalMetadata(metadata, 'indeterminate metadata'), state: 'indeterminate' };
+  }
+
+  function markValidButUnevaluated(url, metadata = {}) {
+    assertMutable();
+    const resource = requireResource(url);
+    assertNotTerminal(resource, 'mark valid-but-unevaluated');
+    if (resource.classification?.state !== 'valid_resource') {
+      throw new Error('resource must be classified as a valid resource before evaluator failure');
+    }
+    resource.validButUnevaluated = canonicalMetadata(metadata, 'evaluator failure metadata');
+  }
+
+  function finalizedState(resource) {
+    const state = stateOf(resource);
+    if (state === 'eligible') return 'unvisited';
+    if (state === 'attempted' || state === 'retrieved' || state === 'valid_resource') {
+      throw new Error(`resource ${resource.normalizedUrl} has unresolved state ${state}`);
+    }
+    return state;
+  }
+
+  function resourceOutput(resource) {
+    const state = finalizedState(resource);
+    const output = {
+      normalized_url: resource.normalizedUrl,
+      original_urls: [...resource.originalUrls].sort(compareStrings),
+      discovery_sources: [...resource.discoverySources.values()].sort((a, b) => (
+        compareStrings(a.source, b.source)
+        || compareStrings(a.url, b.url)
+        || compareStrings(stableString(a), stableString(b))
+      )),
+      state,
+    };
+    if (resource.exclusion) output.exclusion = resource.exclusion;
+    if (resource.attemptHistory.length > 0) output.attempt_history = resource.attemptHistory;
+    if (resource.retrieval) output.retrieval = resource.retrieval;
+    if (resource.classification) output.classification = resource.classification;
+    if (resource.evaluation) output.evaluation = resource.evaluation;
+    if (resource.failure) output.failure = resource.failure;
+    if (resource.indeterminate) output.indeterminate = resource.indeterminate;
+    if (resource.validButUnevaluated) output.evaluator_failure = resource.validButUnevaluated;
+    return output;
+  }
+
+  function finalize(stopReason, options = {}) {
+    assertMutable();
+    if (!STOP_REASONS.has(stopReason)) throw new Error(`unknown stop reason: ${stopReason}`);
+    const {
+      discoveryStatus = 'complete',
+      discoveryMethods,
+      discoveryLimitations = [],
+      limitations = [],
+      preview = false,
+    } = options;
+    if (!DISCOVERY_STATUSES.has(discoveryStatus)) {
+      throw new Error(`unknown discovery status: ${discoveryStatus}`);
+    }
+
+    const provisional = [];
+    if (preview) {
+      for (const resource of resources.values()) {
+        if (resource.classification?.state === 'valid_resource' && !resource.evaluation && !resource.validButUnevaluated) {
+          resource.validButUnevaluated = { reason: 'evaluation_pending' };
+          provisional.push(resource);
+        }
+      }
+    }
+    const outputResources = [...resources.values()]
+      .map(resourceOutput)
+      .sort((a, b) => compareStrings(a.normalized_url, b.normalized_url));
+    const stateCount = (state) => outputResources.filter((resource) => resource.state === state).length;
+    const populations = {
+      discovered: outputResources.length,
+      eligible: outputResources.length - stateCount('excluded'),
+      excluded: stateCount('excluded'),
+      attempted: outputResources.filter((resource) => resource.attempt_history).length,
+      retrieved: outputResources.filter((resource) => resource.retrieval).length,
+      valid_resource: outputResources.filter((resource) => resource.classification?.state === 'valid_resource').length,
+      evaluated: stateCount('evaluated'),
+      valid_but_unevaluated: stateCount('valid_but_unevaluated'),
+      failed: stateCount('failed'),
+      indeterminate: stateCount('indeterminate'),
+      unvisited: stateCount('unvisited'),
+    };
+    const methods = discoveryMethods === undefined
+      ? [...new Set(outputResources.flatMap((resource) => resource.discovery_sources.map(({ source }) => source)))].sort(compareStrings)
+      : sortedUniqueStrings(discoveryMethods, 'discoveryMethods');
+    const coverage = {
+      schema_version: COVERAGE_SCHEMA_VERSION,
+      normalization_version: normalizationVersion,
+      requested_scope: {
+        start_url: startUrl,
+        origin: parsedStartUrl.origin,
+        max_pages: maxPages,
+        time_budget_seconds: timeBudgetSeconds,
+      },
+      discovery: {
+        status: discoveryStatus,
+        methods,
+        limitations: sortedUniqueStrings(discoveryLimitations, 'discoveryLimitations'),
+      },
+      populations,
+      resources: outputResources,
+      stop_reason: stopReason,
+      coverage_status: coverageStatusFor({ stopReason, discoveryStatus, populations }),
+      reconciliation: { valid: false, errors: ['not reconciled'] },
+      limitations: sortedUniqueStrings(limitations, 'limitations'),
+    };
+    coverage.reconciliation = reconcileCoverage(coverage);
+    if (!coverage.reconciliation.valid) {
+      throw new Error(`coverage reconciliation failed: ${coverage.reconciliation.errors.join('; ')}`);
+    }
+    const schemaValidation = validateAgainst('audit-coverage.schema.json', coverage);
+    if (!schemaValidation.valid) {
+      throw new Error(`audit coverage invalid: ${schemaValidation.errors.join('; ')}`);
+    }
+    for (const resource of provisional) resource.validButUnevaluated = null;
+    if (!preview) finalized = true;
+    return coverage;
+  }
+
+  // Read-only state inspection for detectors that must distinguish an
+  // unvisited sitemap URL from an observed retrieval failure. This does not
+  // expose mutable ledger internals or alter reconciliation.
+  function stateFor(url) {
+    const resource = resources.get(normalizedUrl(url));
+    return resource ? stateOf(resource) : null;
+  }
+
+  return {
+    discover,
+    exclude,
+    attempt,
+    retrieve,
+    classify,
+    evaluate,
+    fail,
+    markIndeterminate,
+    markValidButUnevaluated,
+    stateFor,
+    preview: (stopReason, options = {}) => finalize(stopReason, { ...options, preview: true }),
+    finalize,
+  };
+}