@nebulacomponents/citable 1.19.0 → 1.20.0

package/src/extractor/site.js

@@ -3,7 +3,106 @@ import path from 'node:path';
 import { extractPage } from './page.js';
 import { parseRobots } from '../crawler/robots.js';
 import { parseSitemap } from '../crawler/sitemap.js';
+import { collectSitemapTopology } from '../crawler/sitemapCollector.js';
 import { fetchUrl } from '../crawler/fetch.js';
+import { classifyResource } from '../crawler/resourceValidity.js';
+import { createUrlIdentity } from '../crawler/urlIdentity.js';
+import { createCoverageLedger } from '../evidence/coverage.js';
+import { hashPageArtifact } from '../evidence/hashes.js';
+
+const MAX_PAGE_FETCH_ATTEMPTS = 100;
+const SAFE_FETCH_ERROR_CODES = new Set([
+  'FETCH_ABORTED', 'FETCH_BODY_LIMIT', 'FETCH_ERROR', 'FETCH_REDIRECT_INVALID',
+  'FETCH_REDIRECT_LIMIT', 'FETCH_REDIRECT_ORIGIN', 'FETCH_TIMEOUT',
+  'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH',
+  'ENOTFOUND', 'EPIPE', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+function sanitizeEvidenceUrl(rawUrl) {
+  try {
+    const url = new URL(String(rawUrl));
+    url.hash = '';
+    if (url.search) url.search = '?[REDACTED]';
+    return url.href;
+  } catch {
+    return '[invalid-url]';
+  }
+}
+
+function safeErrorCode(value, fallback = 'FETCH_ERROR') {
+  return typeof value === 'string' && SAFE_FETCH_ERROR_CODES.has(value) ? value : fallback;
+}
+
+function finiteNonNegative(value) {
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function sanitizeFetchAttempts(attempts) {
+  if (!Array.isArray(attempts)) return { attempts: [], truncated: false };
+  const bounded = attempts.slice(0, MAX_PAGE_FETCH_ATTEMPTS).map((rawAttempt, index) => {
+    const attempt = rawAttempt && typeof rawAttempt === 'object' ? rawAttempt : {};
+    const outcome = attempt.outcome === 'response' ? 'response' : 'error';
+    return {
+      attempt: Number.isInteger(attempt.attempt) && attempt.attempt > 0 ? attempt.attempt : index + 1,
+      url: sanitizeEvidenceUrl(attempt.url),
+      startedAtMs: finiteNonNegative(attempt.startedAtMs),
+      endedAtMs: finiteNonNegative(attempt.endedAtMs),
+      elapsedMs: finiteNonNegative(attempt.elapsedMs),
+      outcome,
+      status: Number.isInteger(attempt.status) && attempt.status >= 100 && attempt.status <= 599
+        ? attempt.status
+        : null,
+      errorCode: outcome === 'error' ? safeErrorCode(attempt.errorCode) : null,
+      retryDecision: ['retry', 'stop', 'redirect', 'complete'].includes(attempt.retryDecision)
+        ? attempt.retryDecision
+        : 'stop',
+    };
+  });
+  return { attempts: bounded, truncated: attempts.length > MAX_PAGE_FETCH_ATTEMPTS };
+}
+
+function sanitizedFetchError(rawUrl, error) {
+  const attempts = sanitizeFetchAttempts(error?.attempts).attempts;
+  const reason = safeErrorCode(error?.code, attempts.at(-1)?.errorCode ?? 'FETCH_ERROR');
+  return `${sanitizeEvidenceUrl(rawUrl)}: ${reason}`;
+}
+
+function sanitizedSitemapError(error) {
+  const reason = typeof error?.reason === 'string' && /^[a-z0-9_]{1,80}$/.test(error.reason)
+    ? error.reason
+    : 'sitemap_error';
+  return `${sanitizeEvidenceUrl(error?.url)}: ${reason}`;
+}
+
+function attachResourceMetadata(page, {
+  requestedUrl,
+  bodyComplete = true,
+  fetchAttempts = [],
+} = {}) {
+  const effectiveUrl = page.url;
+  const declaredCanonicalUrl = page.canonicals[0] ?? null;
+  page.requestedUrl = requestedUrl ?? effectiveUrl;
+  page.bodyComplete = bodyComplete === true;
+  const sanitizedAttempts = sanitizeFetchAttempts(fetchAttempts);
+  page.fetchAttempts = sanitizedAttempts.attempts;
+  page.fetchAttemptsTruncated = sanitizedAttempts.truncated;
+  page.resourceValidity = classifyResource({
+    status: page.status,
+    headers: page.headers,
+    body: page.rawHtml,
+    bodyComplete: page.bodyComplete,
+    requestedUrl: page.requestedUrl,
+    effectiveUrl,
+  });
+  page.urlIdentity = createUrlIdentity({
+    requestedUrl: page.requestedUrl,
+    effectiveUrl,
+    redirectChain: page.redirectChain,
+    declaredCanonicalUrl,
+  });
+  page.artifact_hash = hashPageArtifact(page);
+  return page;
+}
 
 /**
  * Build a SiteModel from a directory of built/static HTML output.
@@ -27,16 +126,17 @@ export function buildSiteFromDir(dir, { baseUrl = 'https://example.test' } = {})
         let urlPath = '/' + rel;
         if (urlPath.endsWith('/index.html')) urlPath = urlPath.slice(0, -'index.html'.length);
         const t = transport['/' + rel] || transport[urlPath] || {};
-        pages.push(
-          extractPage({
-            url: new URL(urlPath, baseUrl).href,
-            html: fs.readFileSync(p, 'utf8'),
-            status: t.status ?? 200,
-            headers: { 'content-type': 'text/html', ...(t.headers || {}) },
-            sourceFile: p,
-            redirectChain: [],
-          })
-        );
+        const responseBody = fs.readFileSync(p);
+        const page = extractPage({
+          url: new URL(urlPath, baseUrl).href,
+          html: responseBody.toString('utf8'),
+          responseBody,
+          status: t.status ?? 200,
+          headers: { 'content-type': 'text/html', ...(t.headers || {}) },
+          sourceFile: p,
+          redirectChain: [],
+        });
+        pages.push(attachResourceMetadata(page, { requestedUrl: page.url }));
       }
     }
   };
@@ -62,68 +162,216 @@ export function buildSiteFromDir(dir, { baseUrl = 'https://example.test' } = {})
 
 /** Build a SiteModel by fetching a deployed URL set (target URL + same-origin discovery, bounded). */
 export async function buildSiteFromUrl(startUrl, {
-  maxPages = 50, userAgent, pageMaxBytes = 5 * 1024 * 1024,
+  maxPages = 500, timeBudgetSeconds = 1800, userAgent, pageMaxBytes = 5 * 1024 * 1024,
+  // Collection is intentionally sequential. Reject unsupported values rather
+  // than silently changing reproducibility or budget semantics.
+  concurrency = 1,
   robotsMaxBytes = 512 * 1024, sitemapMaxBytes = 5 * 1024 * 1024,
+  sitemapMaxDepth = 4, sitemapMaxDocuments = 1000,
+  sitemapMaxUncompressedBytes = 20 * 1024 * 1024,
+  sitemapMaxTotalUncompressedBytes = 100 * 1024 * 1024,
+  sitemapMaxDiscoveredUrls = 50_000, sitemapMaxQueuedDocuments = 1000,
+  sitemapMaxRawEntries = 100_000, sitemapMaxXmlTokens = 500_000,
   fetcher = fetchUrl,
+  now = () => performance.now(),
 } = {}) {
+  if (concurrency !== 1) {
+    throw new RangeError(`URL collection concurrency is fixed at 1; received ${String(concurrency)}`);
+  }
   const origin = new URL(startUrl).origin;
-  const seen = new Set();
-  const queue = [startUrl];
+  const coverageLedger = createCoverageLedger({ startUrl, maxPages, timeBudgetSeconds });
+  const startedAt = now();
+  const timeExpired = () => now() - startedAt >= timeBudgetSeconds * 1000;
   const pages = [];
   const errors = [];
-  while (queue.length && pages.length < maxPages) {
-    const url = queue.shift();
-    const key = url.replace(/#.*$/, '');
-    if (seen.has(key)) continue;
-    seen.add(key);
+  let stopReason = 'frontier_exhausted';
+  const timeBudgetStopped = () => {
+    if (!timeExpired()) return false;
+    if (stopReason === 'frontier_exhausted') stopReason = 'time_budget_exhausted';
+    return true;
+  };
+
+  // Robots and sitemap topology are collected first so sitemap-only pages share
+  // the same bounded, deduplicated frontier as pages found through HTML links.
+  let robotsText = null;
+  if (!timeBudgetStopped()) {
     try {
-      const res = await fetcher(url, { userAgent, maxBodyBytes: pageMaxBytes });
+      const robotsUrl = new URL('/robots.txt', origin).href;
+      const response = await fetcher(robotsUrl, { userAgent, maxBodyBytes: robotsMaxBytes });
+      if (response.status === 200) robotsText = response.body;
+    } catch {
+      // Missing robots remains represented by robotsText=null for existing detectors.
+    }
+    timeBudgetStopped();
+  }
+
+  const declaredSitemaps = robotsText != null ? parseRobots(robotsText).sitemaps : [];
+  const sitemapEntries = declaredSitemaps.length
+    ? declaredSitemaps
+    : [new URL('/sitemap.xml', origin).href];
+  const sitemapTopology = await collectSitemapTopology(sitemapEntries, {
+    fetcher,
+    maxDepth: sitemapMaxDepth,
+    maxDocuments: sitemapMaxDocuments,
+    maxUncompressedBytes: sitemapMaxUncompressedBytes,
+    maxTotalUncompressedBytes: sitemapMaxTotalUncompressedBytes,
+    maxDiscoveredUrls: sitemapMaxDiscoveredUrls,
+    maxQueuedDocuments: sitemapMaxQueuedDocuments,
+    maxRawEntries: sitemapMaxRawEntries,
+    maxXmlTokens: sitemapMaxXmlTokens,
+    sitemapMaxBytes,
+    origin,
+    userAgent,
+    shouldStop: timeExpired,
+  });
+  if (sitemapTopology.stop_reasons.includes('time_budget_exhausted')) timeBudgetStopped();
+  for (const error of sitemapTopology.errors) {
+    errors.push(sanitizedSitemapError(error));
+  }
+  const sitemaps = sitemapTopology.documents
+    .filter((document) => document.http_status === 200 && document.parsed?.rootValid)
+    .map((document) => ({
+      source: document.effective_url,
+      parsed: document.parsed,
+      status: document.status,
+      failure_reason: document.failure_reason,
+    }));
+
+  const seen = new Set();
+  const queued = new Set();
+  const queue = [];
+  const enqueuePage = (rawUrl, source, base = origin) => {
+    let url;
+    let requestedUrl;
+    try {
+      const raw = String(rawUrl).trim();
+      url = new URL(raw, base);
+      url.hash = '';
+      const fragmentAt = raw.indexOf('#');
+      const withoutFragment = fragmentAt === -1 ? raw : raw.slice(0, fragmentAt);
+      if (/^[A-Za-z][A-Za-z\d+.-]*:\/\//.test(withoutFragment)) requestedUrl = withoutFragment;
+      else if (withoutFragment.startsWith('//')) requestedUrl = `${new URL(base).protocol}${withoutFragment}`;
+      else requestedUrl = url.href;
+    } catch {
+      return;
+    }
+    if (url.origin !== origin || isProviderUtilityPath(url.pathname) || seen.has(url.href) || queued.has(url.href)) return;
+    coverageLedger.discover(url.href, source, { requested_url: requestedUrl });
+    queued.add(url.href);
+    queue.push({ url: url.href, requestedUrl, source });
+  };
+  enqueuePage(startUrl, 'start');
+  for (const entry of sitemapTopology.urls) enqueuePage(entry.url, 'sitemap');
+
+  while (queue.length && stopReason !== 'time_budget_exhausted') {
+    if (timeBudgetStopped()) break;
+    if (seen.size >= maxPages) {
+      stopReason = 'page_budget_exhausted';
+      break;
+    }
+    const next = queue.shift();
+    queued.delete(next.url);
+    seen.add(next.url);
+    coverageLedger.attempt(next.url, { attempt: 1, requested_url: next.requestedUrl });
+    try {
+      const response = await fetcher(next.url, { userAgent, maxBodyBytes: pageMaxBytes });
+      coverageLedger.retrieve(next.url, {
+        status: response.status,
+        effective_url: response.url,
+        body_complete: response.bodyComplete ?? true,
+      });
       const page = extractPage({
-        url: res.url, html: res.body, status: res.status, headers: res.headers, redirectChain: res.redirectChain,
+        url: response.url, html: response.body, responseBody: response.bodyBytes ?? response.body, status: response.status,
+        headers: response.headers, redirectChain: response.redirectChain,
       });
-      page.requestedUrl = url;
+      attachResourceMetadata(page, {
+        requestedUrl: next.requestedUrl,
+        bodyComplete: response.bodyComplete ?? true,
+        fetchAttempts: response.attempts ?? [],
+      });
+      page.crawlUrl = next.url;
+      if (page.resourceValidity?.state === 'valid_resource') {
+        coverageLedger.classify(next.url, {
+          state: 'valid_resource',
+          resource_id: page.urlIdentity?.resource_id,
+          requested_url: page.urlIdentity?.requested?.url ?? page.requestedUrl ?? null,
+          effective_url: page.urlIdentity?.effective?.url ?? page.url ?? null,
+          canonical_url: page.urlIdentity?.canonical?.url ?? null,
+          url_identity: page.urlIdentity,
+          response_body_hash: page.response_body_hash,
+          extracted_text_hash: page.extracted_text_hash,
+          structured_data_hash: page.structured_data_hash,
+          evidence_hash: page.evidence_hash,
+          artifact_hash: page.artifact_hash,
+        });
+      } else {
+        coverageLedger.markIndeterminate(next.url, {
+          reason_codes: page.resourceValidity?.reason_codes || ['resource_invalid'],
+          resource_validity: page.resourceValidity?.state || 'indeterminate',
+        });
+      }
+      page.discoverySource = next.source;
       pages.push(page);
-      if (String(res.headers['content-type'] || '').includes('text/html')) {
-        for (const l of page.links) {
-          try {
-            const u = new URL(l.href, res.url);
-            u.hash = '';
-            if (u.origin === origin && !isProviderUtilityPath(u.pathname) && !seen.has(u.href)) queue.push(u.href);
-          } catch { /* unresolvable href — surfaced by LINK detectors */ }
+      if (timeBudgetStopped()) break;
+      if (String(response.headers['content-type'] || '').includes('text/html')) {
+        for (const link of page.links) {
+          if (timeBudgetStopped()) break;
+          enqueuePage(link.href, 'link', response.url);
         }
       }
-    } catch (err) {
-      errors.push(`${url}: ${err.message}`);
+      if (stopReason === 'time_budget_exhausted') break;
+    } catch (error) {
+      coverageLedger.fail(next.url, { reason: error?.code || 'FETCH_ERROR' });
+      errors.push(sanitizedFetchError(next.url, error));
     }
   }
-  let robotsText = null;
-  const sitemaps = [];
-  try {
-    const r = await fetcher(new URL('/robots.txt', origin).href, { userAgent, maxBodyBytes: robotsMaxBytes });
-    if (r.status === 200) robotsText = r.body;
-  } catch { /* recorded as missing robots */ }
-  const smUrls = robotsText ? parseRobots(robotsText).sitemaps : [new URL('/sitemap.xml', origin).href];
-  for (const sm of smUrls) {
-    try {
-      const sitemapUrl = new URL(sm, origin);
-      if (sitemapUrl.origin !== origin) {
-        errors.push(`${sitemapUrl.href}: sitemap URL leaves audited origin`);
-        continue;
-      }
-      const r = await fetcher(sitemapUrl.href, { userAgent, maxBodyBytes: sitemapMaxBytes });
-      if (r.status === 200) sitemaps.push({ source: sm, parsed: parseSitemap(r.body) });
-    } catch { /* absence handled by TECH detectors */ }
-  }
-  const pendingUrls = [...new Set(queue.map((url) => url.replace(/#.*$/, '')).filter((url) => !seen.has(url)))];
+  if (stopReason === 'frontier_exhausted') timeBudgetStopped();
+  const pendingUrls = queue.map((entry) => entry.url).filter((url) => !seen.has(url));
   const crawl = {
     maxPages,
+    timeBudgetSeconds,
+    stopReason,
     pagesFetched: pages.length,
-    truncated: pages.length >= maxPages && pendingUrls.length > 0,
+    truncated: stopReason === 'page_budget_exhausted' || stopReason === 'time_budget_exhausted',
     pendingUrlCount: pendingUrls.length,
     pendingUrls,
+    sitemapStopReasons: [...sitemapTopology.stop_reasons],
+    sitemapTopology: {
+      status: sitemapTopology.status,
+      stopReasons: [...sitemapTopology.stop_reasons],
+      limitations: [...sitemapTopology.limitations],
+    },
   };
   const site = assembleSite({ baseUrl: origin, pages, robotsText, sitemaps, transport: {}, mode: 'url', location: startUrl, crawl });
+  site.coverageLedger = coverageLedger;
+  site.coverageOptions = {
+    discoveryStatus: sitemapTopology.status,
+    discoveryMethods: ['start', 'link', 'sitemap'],
+    discoveryLimitations: [...sitemapTopology.limitations],
+    limitations: [...sitemapTopology.limitations],
+  };
+  site.previewCoverage = () => coverageLedger.preview(stopReason, site.coverageOptions);
+  site.finalizeCoverage = ({ evaluated = true } = {}) => {
+    if (evaluated) {
+      for (const page of pages) {
+        if (page.resourceValidity?.state === 'valid_resource') {
+          coverageLedger.evaluate(page.crawlUrl || page.url, {
+            evaluator: 'audit-detectors',
+            detector_scope: 'selected',
+          });
+        }
+      }
+    } else {
+      for (const page of pages) {
+        if (page.resourceValidity?.state === 'valid_resource') {
+          coverageLedger.markValidButUnevaluated(page.crawlUrl || page.url, { reason: 'not_evaluated' });
+        }
+      }
+    }
+    return coverageLedger.finalize(stopReason, site.coverageOptions);
+  };
   site.fetchErrors = errors;
+  site.sitemapTopology = sitemapTopology;
   return site;
 }
 

package/src/reporting/executiveCroReport.js

@@ -29,6 +29,7 @@ import {
 } from '../shared/htmlEscape.js';
 import { extractHostname } from '../shared/domainUtils.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { assertEpistemicLanguage, hasVerifiedEvidenceScope } from '../shared/epistemicLanguage.js';
 
 function formatVal(v, suffix = '') {
   if (v === null || v === undefined) return 'NOT OBSERVED';
@@ -529,6 +530,13 @@ export async function buildExecutiveCroReport(root, options = {}) {
     source_findings_count: findings.length,
     integrity_hash: resolved.integrity_hash,
     synthetic_evidence: isSample,
+    package_verified: resolved.package_verified === true,
+    integrity_mode: resolved.integrity_mode || 'unknown',
+    legacy: resolved.legacy === true,
+    coverage_status: resolved.coverage_status || 'indeterminate',
+    determination_status: resolved.determination_status || 'indeterminate',
+    evaluated: resolved.coverage?.populations?.evaluated ?? null,
+    eligible: resolved.coverage?.populations?.eligible ?? null,
   };
 
   const report = {
@@ -542,7 +550,7 @@ export async function buildExecutiveCroReport(root, options = {}) {
     epistemological_framework: {
       observation: 'Raw empirical facts measured directly from DOM geometry, HTTP status, or analytics telemetry',
       hypothesis: 'Testable causal explanations predicting why the observed friction occurs',
-      causation: 'Statistically verified outcomes demonstrated under controlled A/B experiments with SRM checks',
+      causation: 'No current causal outcome is established; controlled A/B experiment evidence is required',
       unknowns: 'Gaps in telemetry or attribution that require further instrumentation before forming hypotheses',
     },
     pillars: {
@@ -588,7 +596,11 @@ export async function buildExecutiveCroReport(root, options = {}) {
 /**
  * Render CRO Executive Report as GitHub-flavored Markdown
  */
-export function renderCroReportMarkdown(report) {
+export function renderCroReportMarkdown(report, evidenceContext = null) {
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const causalEvidenceVerified = verifiedScope && context.causal_evidence_verified === true;
+  const evidenceRegisterTitle = `${verifiedScope ? 'Verified Conversion Evidence Register' : 'Conversion Evidence Register (scope-limited; verified status not established)'}`;
   const p = report.pillars;
   const ds = report.decision_summary;
   const lines = [
@@ -597,7 +609,7 @@ export function renderCroReportMarkdown(report) {
     `- **Client / Property**: \`${sanitizeForMarkdown(report.client_name)}\` (\`${sanitizeForMarkdown(report.target_domain)}\`)`,
     `- **Generated At**: \`${report.generated_at}\``,
     `- **Conversion Readiness Index**: **${report.overall_conversion_readiness} / 100**`,
-    `- **Evidence Register Traceability**: ${report.evidence_register.length} verified evidence references`,
+    `- **Evidence Register Traceability**: ${report.evidence_register.length} evidence references (authority and scope recorded below)`,
     `- **Generation Mode**: \`${report.generation_provenance.generation_mode}\`${report.generation_provenance.synthetic_evidence ? ' *(Synthetic Demo Evidence)*' : ''}`,
     ``,
     `> **Scientific Epistemology & Governance Notice**: Citable enforces a strict separation between **Observable Facts**, **Predictive Hypotheses**, and **Causal Evidence**. In adherence to empirical governance, **no conversion rates, ARR lift, or metric improvements are guaranteed**.`,
@@ -613,8 +625,8 @@ export function renderCroReportMarkdown(report) {
     `*(Testable causal predictions requiring validation under controlled experimentation)*`,
     ...ds.evidence_supported_hypotheses.map((h) => `- [ ] **[HYPOTHESIS]** ${sanitizeForMarkdown(h)}`),
     ``,
-    `### 3. Causal Findings (Verified Under Controlled Experiments)`,
-    `*(Demonstrated metric shifts under A/B testing with Sample Ratio Mismatch guardrails)*`,
+    `### 3. ${causalEvidenceVerified ? 'Causal Findings (Verified Under Controlled Experiments)' : 'Causal Findings (Causal Evidence Not Established)'}`,
+    `*(${causalEvidenceVerified ? 'Demonstrated metric shifts under A/B testing with Sample Ratio Mismatch guardrails' : 'No current causal outcome is established from this report; controlled experiment evidence is required'})*`,
     ...ds.causal_findings.map((c) => `- [=] **[CAUSAL]** ${sanitizeForMarkdown(c)}`),
     ``,
     `### 4. Critical Unresolved Unknowns (Measurement Gaps)`,
@@ -694,7 +706,7 @@ export function renderCroReportMarkdown(report) {
     `- **Evidence Link**: \`${p[15].data.evidence_ref}\``,
     ...(p[15].data.top_customer_objections || []).map((o) => `- "${sanitizeForMarkdown(o)}"`),
     ``,
-    `## 15. Verified Conversion Evidence Register`,
+    `## 15. ${evidenceRegisterTitle}`,
     `| Evidence ID | Source Channel | Methodology | Confidence | Observation Date |`,
     `| :--- | :--- | :--- | :--- | :--- |`,
     ...report.evidence_register.map((e) => `| **${e.evidence_id}** | \`${escapeMarkdownTableCell(e.source)}\` | ${escapeMarkdownTableCell((e.methodology || '').slice(0, 50))}... | \`${e.confidence_level}\` | ${e.observation_date} |`),
@@ -720,16 +732,24 @@ export function renderCroReportMarkdown(report) {
     ``,
   ];
 
-  return lines.join('\n');
+  const rendered = lines.join('\n');
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
  * Render CRO Executive Report as Standalone Enterprise HTML
  */
-export function renderCroReportHtml(report) {
+export function renderCroReportHtml(report, evidenceContext = null) {
   const p = report.pillars;
   const ds = report.decision_summary;
-  return `<!DOCTYPE html>
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const causalEvidenceVerified = verifiedScope && context.causal_evidence_verified === true;
+  const evidenceRegisterTitle = verifiedScope
+    ? 'Verified Conversion Evidence Register'
+    : 'Conversion Evidence Register (scope-limited; verified status not established)';
+  const rendered = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
@@ -817,13 +837,13 @@ export function renderCroReportHtml(report) {
 
     <div class="epistemic-box" style="border-left: 4px solid var(--accent-light);">
       <span class="epistemic-tag badge-causal">Causal Findings</span>
-      <p style="font-size:12px; color:var(--muted); margin: 0 0 8px 0;">Statistically verified outcomes verified under controlled A/B experiments with SRM checks.</p>
+      <p style="font-size:12px; color:var(--muted); margin: 0 0 8px 0;">${causalEvidenceVerified ? 'Statistically verified outcomes under controlled A/B experiments with SRM checks.' : 'Causal evidence is not established; controlled A/B experiment evidence is required.'}</p>
       <ul>
         ${ds.causal_findings.map((c) => `<li>${escapeHtml(c)}</li>`).join('')}
       </ul>
     </div>
 
-    <h2 class="section-title">Verified Conversion Evidence Register (${report.evidence_register.length} Observations)</h2>
+    <h2 class="section-title">${evidenceRegisterTitle} (${report.evidence_register.length} Observations)</h2>
     <table>
       <thead>
         <tr>
@@ -858,6 +878,8 @@ export function renderCroReportHtml(report) {
   </div>
 </body>
 </html>`;
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
@@ -865,15 +887,16 @@ export function renderCroReportHtml(report) {
  */
 export async function exportExecutiveCroReport(root, options = {}) {
   const report = await buildExecutiveCroReport(root, options);
+  const evidenceContext = report.generation_provenance;
   const format = options.format || 'markdown';
   let content = '';
 
   if (format === 'html' || format === 'html-brief') {
-    content = renderCroReportHtml(report);
+    content = renderCroReportHtml(report, evidenceContext);
   } else if (format === 'json') {
     content = JSON.stringify(report, null, 2);
   } else {
-    content = renderCroReportMarkdown(report);
+    content = renderCroReportMarkdown(report, evidenceContext);
   }
 
   let outputPath = null;

package/src/reporting/executiveExport.js

@@ -3,6 +3,9 @@ import path from "node:path";
 import { readJson } from "../shared/io.js";
 import { exportExecutiveSearchReport, buildExecutiveSearchReport, renderSearchReportMarkdown, renderSearchReportHtml } from "./executiveSearchReport.js";
 import { exportExecutiveCroReport, buildExecutiveCroReport, renderCroReportMarkdown, renderCroReportHtml } from "./executiveCroReport.js";
+import { downstreamEnvelope } from '../evidence/downstream.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
+import { assertEpistemicLanguage, evidenceScopeStatement } from '../shared/epistemicLanguage.js';
 
 export {
   exportExecutiveSearchReport,
@@ -78,7 +81,7 @@ export async function exportExecutiveReport(root, runId, {
   }
 
   const runsDir = path.join(root, ".citable", "runs");
-  let targetRun = runId;
+  let targetRun = runId && fs.existsSync(path.join(root, '.citable', 'runs', runId)) ? runId : null;
 
   if (!targetRun && fs.existsSync(runsDir)) {
     const runs = fs.readdirSync(runsDir).filter((d) => !d.startsWith("."));
@@ -86,23 +89,41 @@ export async function exportExecutiveReport(root, runId, {
   }
 
   let summary = {
-    counts: { critical: 0, high: 2, medium: 4, low: 1 },
+    counts: { critical: 0, high: 0, medium: 0, low: 0 },
     posture: { retrieval: "eligible", support: "suitable", citation: "observed" },
+    coverage_status: 'indeterminate',
+    determination_status: 'indeterminate',
   };
   let findings = [];
+  let coverage = null;
+  let packageVerified = false;
 
   if (targetRun) {
-    const sumPath = path.join(runsDir, targetRun, "summary.json");
-    if (fs.existsSync(sumPath)) {
-      try { summary = readJson(sumPath); } catch {}
-    }
-    const findPath = path.join(runsDir, targetRun, "findings.json");
-    if (fs.existsSync(findPath)) {
-      try { findings = readJson(findPath); } catch {}
-    }
+    const loaded = loadVerifiedRun(path.join(runsDir, targetRun), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+    summary = loaded.summary || summary;
+    findings = loaded.findings;
+    coverage = loaded.coverage;
+    packageVerified = loaded.verified === true && loaded.integrity_mode === 'sealed';
+    summary.coverage_status = loaded.coverage_status;
+    summary.determination_status = loaded.determination_status;
   }
 
+  const evidence = downstreamEnvelope(coverage);
+  summary.coverage_status = evidence.coverage_status;
+  summary.determination_status = evidence.determination_status;
+  summary.coverage = {
+    ...evidence.evidence_scope,
+    limitations: evidence.limitations,
+  };
+
   let content = "";
+  const evidenceNotice = `Evidence determination: ${summary.determination_status} (coverage: ${summary.coverage_status}; evaluated ${summary.coverage.evaluated ?? 0} of ${summary.coverage.eligible ?? 'unknown'} eligible). ${summary.coverage.limitations.join('; ') || evidenceScopeStatement({
+    coverage_status: summary.coverage_status,
+    determination_status: summary.determination_status,
+    evaluated: summary.coverage.evaluated,
+    eligible: summary.coverage.eligible,
+    package_verified: packageVerified,
+  })}`;
 
   if (format === "html-brief") {
     content = `<!DOCTYPE html>
@@ -136,6 +157,7 @@ export async function exportExecutiveReport(root, runId, {
   <div class="disclosure">
     <strong>Regulatory & Governance Notice:</strong> Citable measures observable retrieval suitability, source extraction fidelity, and external AI citation outcomes. Citable does not guarantee search crawling, indexing, ranking, citation, recommendation, or conversion.
   </div>
+  <p class="disclosure"><strong>${evidenceNotice}</strong></p>
 
   <div class="kpi-grid">
     <div class="kpi-card"><div>Critical Risks</div><div class="kpi-val ${(summary.counts?.critical || 0) > 0 ? "crit" : "healthy"}">${summary.counts?.critical || 0}</div></div>
@@ -150,10 +172,7 @@ export async function exportExecutiveReport(root, runId, {
       <tr><th>Detector</th><th>Severity</th><th>Summary</th><th>Required Remediation</th></tr>
     </thead>
     <tbody>
-      ${(findings.length > 0 ? findings : [
-        { detector_id: "CRO-015", severity: "low", summary: "Mobile touch target below 44px on primary CTA", remediation: "Increase button min-height to 48px" },
-        { detector_id: "GEO-008", severity: "high", summary: "Attribution distortion in AI search citation", remediation: "Corroborate claims directly on landing page" },
-      ]).map((f) => `
+      ${(findings.length > 0 ? findings : [{ detector_id: "—", severity: "informational", summary: evidenceNotice, remediation: "Collect sufficient evidence before drawing a site-wide determination" }]).map((f) => `
         <tr>
           <td><code>${f.detector_id}</code></td>
           <td><span class="badge badge-${f.severity}">${f.severity.toUpperCase()}</span></td>
@@ -174,11 +193,13 @@ export async function exportExecutiveReport(root, runId, {
 - **High Severity Findings**: ${summary.counts?.high || 0}
 - **Medium Severity Findings**: ${summary.counts?.medium || 0}
 
+> **${evidenceNotice}** Findings remain limited to the evaluated evidence scope.
+
 > Citable does not guarantee crawling, indexing, ranking, citation, or conversion.
 
 <!-- slide -->
 ## Prioritized Action Items
-${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f.summary}`).join("\n") || "- No blocking findings detected."}
+${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f.summary}`).join("\n") || `- No determination established from the available evidence (${summary.determination_status || 'indeterminate'}).`}
 `;
   } else if (format === "slides") {
     const fsa = findings.reduce((acc, f) => {
@@ -263,7 +284,7 @@ ${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f
     <h2>Prioritized Remediations</h2>
     <p>Every finding maps directly to a production-ready, accessible Nebula Component:</p>
     <div style="background:#1e293b; border-radius:0.75rem; padding:1.5rem; border:1px solid #334155;">
-      ${findings.slice(0, 4).map((f) => `<div style="padding:0.5rem 0; border-bottom:1px solid #334155; font-size:1.1rem;"><strong>[${f.detector_id || "CRO"}]</strong>: ${f.summary || "Conversion action friction"}</div>`).join("") || "<p>All conversion pathways verified clean.</p>"}
+      ${findings.slice(0, 4).map((f) => `<div style="padding:0.5rem 0; border-bottom:1px solid #334155; font-size:1.1rem;"><strong>[${f.detector_id || "CRO"}]</strong>: ${f.summary || "Conversion action friction"}</div>`).join("") || `<p>No determination established from the available evidence (${summary.determination_status || 'indeterminate'}).</p>`}
     </div>
     <div style="margin-top:1.5rem; font-family:monospace; background:#0f172a; padding:1rem; border-radius:0.5rem; border:1px solid #334155; color:#38bdf8;">
       $ npx @nebulacomponents/citable remediate --finding CRO-007 --write
@@ -300,6 +321,14 @@ ${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f
     fs.writeFileSync(path.resolve(root, output), content, "utf8");
   }
 
+  const languageContext = {
+    coverage_status: summary.coverage_status,
+    determination_status: summary.determination_status,
+    evaluated: summary.coverage.evaluated,
+    eligible: summary.coverage.eligible,
+    package_verified: packageVerified,
+  };
+  assertEpistemicLanguage(content, languageContext);
   return {
     format,
     client_name: clientName,