@nebulacomponents/citable 1.19.0 → 1.20.0

package/src/reporting/executiveSearchReport.js

@@ -31,6 +31,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';
@@ -620,6 +621,13 @@ export async function buildExecutiveSearchReport(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 = {
@@ -667,7 +675,15 @@ export async function buildExecutiveSearchReport(root, options = {}) {
 /**
  * Render Search Executive Report as GitHub-flavored Markdown
  */
-export function renderSearchReportMarkdown(report) {
+export function renderSearchReportMarkdown(report, evidenceContext = null) {
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const scopedValue = (value) => {
+    if (!verifiedScope && typeof value === 'string' && /\b(?:verified|clean|resolved|optimal|passed)\b|(?:verified_source|clean_profile)/i.test(value)) return 'NOT ESTABLISHED';
+    return value;
+  };
+  const scopedFormat = (value, suffix = '') => scopedValue(formatVal(value, suffix));
+  const evidenceRegisterTitle = `${verifiedScope ? 'Verified Evidence Register' : 'Evidence Register (scope-limited; verified status not established)'} (Traceability Engine)`;
   const p = report.pillars;
   const lines = [
     `# ${sanitizeForMarkdown(report.report_title)}`,
@@ -675,7 +691,7 @@ export function renderSearchReportMarkdown(report) {
     `- **Client / Property**: \`${sanitizeForMarkdown(report.client_name)}\` (\`${sanitizeForMarkdown(report.target_domain)}\`)`,
     `- **Generated At**: \`${report.generated_at}\``,
     `- **Overall Search & AEO Readiness Score**: **${report.overall_readiness_score} / 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)*' : ''}`,
     ``,
     `> **Operating Premise & Governance Notice**: This executive report presents observable technical search infrastructure, content extraction posture, and controlled citation behavior. In adherence to Citable governance principles, **no search ranking, AI citation, or conversion outcomes are guaranteed**.`,
@@ -684,7 +700,7 @@ export function renderSearchReportMarkdown(report) {
     `## Executive Decision Summary (Traceable Conclusions)`,
     ``,
     `### 1. Confirmed Findings (Deterministic Observations)`,
-    ...report.decision_summary.confirmed_findings.map((f) => `- [x] **[VERIFIED]** ${sanitizeForMarkdown(f)}`),
+    ...report.decision_summary.confirmed_findings.map((f) => `- [x] **[OBSERVED]** ${sanitizeForMarkdown(f)}`),
     ``,
     `### 2. Inferred Opportunities (Modeled Projections)`,
     ...report.decision_summary.inferred_opportunities.map((o) => `- [ ] **[OPPORTUNITY]** ${sanitizeForMarkdown(o)}`),
@@ -703,13 +719,13 @@ export function renderSearchReportMarkdown(report) {
     `- **Evidence Link**: \`${p[1].data.evidence_ref}\``,
     `- **Google Organic Indexing**: ${formatVal(p[1].data.google_organic?.indexed_status).toUpperCase()}`,
     `- **Google AI Overviews**: ${formatVal(p[1].data.google_ai_overviews?.inclusion_rate_pct, '%')} inclusion rate (Risk: \`${formatVal(p[1].data.google_ai_overviews?.risk_exposure)}\`)`,
-    `- **AI Engine Presence**: Perplexity (\`${formatVal(p[1].data.ai_answer_engines?.perplexity)}\`), ChatGPT (\`${formatVal(p[1].data.ai_answer_engines?.chatgpt_search)}\`), Copilot (\`${formatVal(p[1].data.ai_answer_engines?.copilot)}\`)`,
+    `- **AI Engine Presence**: Perplexity (\`${scopedFormat(p[1].data.ai_answer_engines?.perplexity)}\`), ChatGPT (\`${scopedFormat(p[1].data.ai_answer_engines?.chatgpt_search)}\`), Copilot (\`${scopedFormat(p[1].data.ai_answer_engines?.copilot)}\`)`,
     ``,
     `## 2. Technical Search Infrastructure & Core Web Vitals`,
     `- **Evidence Link**: \`${p[2].data.evidence_ref}\``,
-    `- **Crawlability & Canonicals**: ${formatVal(p[2].data.canonical_integrity).toUpperCase()}`,
-    `- **LCP Readiness**: ${formatVal(p[2].data.core_web_vitals?.lcp_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.render_blocking_scripts)} render-blocking assets)`,
-    `- **CLS Readiness**: ${formatVal(p[2].data.core_web_vitals?.cls_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.unsized_images)} unsized images)`,
+    `- **Crawlability & Canonicals**: ${scopedFormat(p[2].data.canonical_integrity).toUpperCase()}`,
+    `- **LCP Readiness**: ${scopedFormat(p[2].data.core_web_vitals?.lcp_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.render_blocking_scripts)} render-blocking assets)`,
+    `- **CLS Readiness**: ${scopedFormat(p[2].data.core_web_vitals?.cls_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.unsized_images)} unsized images)`,
     ``,
     `## 3. Organic Performance & Search Intent Analysis`,
     `- **Evidence Link**: \`${p[3].data.evidence_ref}\``,
@@ -724,7 +740,7 @@ export function renderSearchReportMarkdown(report) {
     ``,
     `## 5. AEO Readiness Assessment (Answer Engine Optimization)`,
     `- **Evidence Link**: \`${p[5].data.evidence_ref}\``,
-    `- **Overall AEO Readiness Score**: **${formatVal(p[5].data.readiness_score)} / 100** (${formatVal(p[5].data.status).toUpperCase()})`,
+    `- **Overall AEO Readiness Score**: **${formatVal(p[5].data.readiness_score)} / 100** (${scopedFormat(p[5].data.status).toUpperCase()})`,
     `- **Direct Answer Density**: ${formatVal(p[5].data.direct_extract_density)}`,
     ``,
     `## 6. GEO Assessment (Generative Engine Optimization)`,
@@ -743,7 +759,7 @@ export function renderSearchReportMarkdown(report) {
     `## 8. Entity & Knowledge Graph Integrity`,
     `- **Evidence Link**: \`${p[8].data.evidence_ref}\``,
     `- **Organization Node Resolved**: ${p[8].data.organization_node_resolved ? 'YES' : 'NO'}`,
-    `- **External Corroboration**: ${formatVal(p[8].data.wikidata_corroboration).toUpperCase()}`,
+    `- **External Corroboration**: ${scopedFormat(p[8].data.wikidata_corroboration).toUpperCase()}`,
     ``,
     `## 9. Structured-Data & Schema Architecture`,
     `- **Evidence Link**: \`${p[9].data.evidence_ref}\``,
@@ -753,12 +769,12 @@ export function renderSearchReportMarkdown(report) {
     `## 10. Competitive Search Intelligence & Share of Voice`,
     `- **Evidence Link**: \`${p[10].data.evidence_ref}\``,
     `- **1st-Party Citation Share**: **${formatVal(p[10].data.first_party_citation_share_pct, '%')}** vs Competitors (${formatVal(p[10].data.top_competitor_share_pct, '%')})`,
-    `- **Primary Gap**: ${formatVal(p[10].data.primary_authority_gap)}`,
+    `- **Primary Gap**: ${scopedFormat(p[10].data.primary_authority_gap)}`,
     ``,
     `## 11. Backlink & Off-Page Authority Profile`,
     `- **Evidence Link**: \`${p[11].data.evidence_ref}\``,
     `- **Referring Domains**: ${formatVal(p[11].data.referring_domains)} (Authority Score: ${formatVal(p[11].data.authority_score)}/100)`,
-    `- **Toxic Domains**: ${formatVal(p[11].data.toxic_domain_count)} flagged (\`${formatVal(p[11].data.disavow_recommendation)}\`)`,
+    `- **Toxic Domains**: ${formatVal(p[11].data.toxic_domain_count)} flagged (\`${scopedFormat(p[11].data.disavow_recommendation)}\`)`,
     ``,
     `## 12. Search Demand & Addressable Market Opportunity`,
   ];
@@ -782,11 +798,11 @@ export function renderSearchReportMarkdown(report) {
     `- **Assisted Conversions Share**: ${formatVal(p[13].data.assisted_conversions_share_pct, '%')}`,
     ``,
     `## 14. Measurement Integrity & Analytics Instrumentation`,
-    `- **GA4 & GSC**: ${formatVal(p[14].data.ga4_instrumentation).toUpperCase()} / ${formatVal(p[14].data.gsc_property_binding).toUpperCase()}`,
+    `- **GA4 & GSC**: ${formatVal(scopedValue(p[14].data.ga4_instrumentation)).toUpperCase()} / ${formatVal(scopedValue(p[14].data.gsc_property_binding)).toUpperCase()}`,
     `- **Consent Mode Data Loss**: ${formatVal(p[14].data.consent_mode_v2_loss_pct, '%')}`,
     `- **Limitations**: ${(p[14].data.known_limitations || []).map((l) => sanitizeForMarkdown(l)).join('; ')}`,
     ``,
-    `## 15. Verified Evidence Register (Traceability Engine)`,
+    `## 15. ${evidenceRegisterTitle}`,
     `| Evidence ID | Source | 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} |`),
@@ -806,15 +822,30 @@ export function renderSearchReportMarkdown(report) {
     ``
   );
 
-  return lines.join('\n');
+  const rendered = lines.join('\n');
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
  * Render Search Executive Report as Standalone Enterprise HTML
  */
-export function renderSearchReportHtml(report) {
+export function renderSearchReportHtml(report, evidenceContext = null) {
   const p = report.pillars;
-  return `<!DOCTYPE html>
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const evidenceRegisterTitle = verifiedScope
+    ? 'Verified Evidence Register'
+    : 'Evidence Register (scope-limited; verified status not established)';
+  const readinessLabel = verifiedScope ? (report.overall_readiness_score >= 70 ? 'Strong observed posture' : 'Needs optimization') : 'Not established';
+  const cwvLabel = verifiedScope && p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'No flagged blockers' : 'Not established';
+  const scopedFormat = (value, suffix = '') => {
+    const rendered = formatVal(value, suffix);
+    return !verifiedScope && typeof rendered === 'string' && /\b(?:verified|clean|resolved|optimal|passed)\b|(?:verified_source|clean_profile)/i.test(rendered)
+      ? 'NOT ESTABLISHED'
+      : rendered;
+  };
+  const rendered = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
@@ -861,12 +892,12 @@ export function renderSearchReportHtml(report) {
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">Composite Search Readiness</div>
         <div class="card-num">${report.overall_readiness_score} / 100</div>
-        <span class="badge ${report.overall_readiness_score >= 70 ? 'badge-success' : 'badge-warning'}">${report.overall_readiness_score >= 70 ? 'Optimal' : 'Needs Optimization'}</span>
+        <span class="badge ${verifiedScope && report.overall_readiness_score >= 70 ? 'badge-success' : 'badge-warning'}">${readinessLabel}</span>
       </div>
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">AEO Direct Extraction</div>
         <div class="card-num">${formatVal(p[5].data.readiness_score)}</div>
-        <span class="badge badge-success">${formatVal(p[5].data.status).toUpperCase()}</span>
+        <span class="badge badge-success">${scopedFormat(p[5].data.status).toUpperCase()}</span>
       </div>
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">E-E-A-T Quality Score</div>
@@ -876,11 +907,11 @@ export function renderSearchReportHtml(report) {
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">Core Web Vitals Blockers</div>
         <div class="card-num">${formatVal(p[2].data.core_web_vitals?.render_blocking_scripts)}</div>
-        <span class="badge ${p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'badge-success' : 'badge-danger'}">${p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'Clean' : 'Action Required'}</span>
+        <span class="badge ${verifiedScope && p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'badge-success' : 'badge-danger'}">${cwvLabel}</span>
       </div>
     </div>
 
-    <h2 class="section-title">Verified Evidence Register (${report.evidence_register.length} Observations)</h2>
+    <h2 class="section-title">${evidenceRegisterTitle} (${report.evidence_register.length} Observations)</h2>
     <table>
       <thead>
         <tr>
@@ -915,6 +946,8 @@ export function renderSearchReportHtml(report) {
   </div>
 </body>
 </html>`;
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
@@ -922,15 +955,16 @@ export function renderSearchReportHtml(report) {
  */
 export async function exportExecutiveSearchReport(root, options = {}) {
   const report = await buildExecutiveSearchReport(root, options);
+  const evidenceContext = report.generation_provenance;
   const format = options.format || 'markdown';
   let content = '';
 
   if (format === 'html' || format === 'html-brief') {
-    content = renderSearchReportHtml(report);
+    content = renderSearchReportHtml(report, evidenceContext);
   } else if (format === 'json') {
     content = JSON.stringify(report, null, 2);
   } else {
-    content = renderSearchReportMarkdown(report);
+    content = renderSearchReportMarkdown(report, evidenceContext);
   }
 
   let outputPath = null;

package/src/reporting/report.js

@@ -1,3 +1,5 @@
+import { assertEpistemicLanguage, evidenceScopeStatement } from '../shared/epistemicLanguage.js';
+
 const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, informational: 4, experimental: 5 };
 
 const RETRIEVAL_NAMESPACES = new Set(['TECH', 'CRAWL', 'LINK', 'HREFLANG']);
@@ -39,7 +41,7 @@ function citationPosture(promptResults, targetOrigin) {
   };
 }
 
-export function summarize(findings, { detectorsRun = [], detectorsSkipped = [], promptResults = [], targetOrigin = null } = {}) {
+export function summarize(findings, { detectorsRun = [], detectorsSkipped = [], promptResults = [], targetOrigin = null, coverage = null } = {}) {
   const bySeverity = {};
   const byNamespace = {};
   const byDiscipline = { seo: 0, aeo: 0, geo: 0 };
@@ -51,6 +53,18 @@ export function summarize(findings, { detectorsRun = [], detectorsSkipped = [],
     for (const d of f.discipline) byDiscipline[d] = (byDiscipline[d] || 0) + 1;
     if (f.classification.deterministic) deterministic++;
   }
+  const coverageIncomplete = coverage && coverage.coverage_status !== 'complete';
+  const posture = {
+    retrieval_eligibility: readinessPosture(findings, detectorsRun, detectorsSkipped, RETRIEVAL_NAMESPACES),
+    source_extraction_and_support: readinessPosture(findings, detectorsRun, detectorsSkipped, SOURCE_NAMESPACES),
+    observed_citation_behavior: citationPosture(promptResults, targetOrigin),
+  };
+  if (coverageIncomplete) {
+    for (const key of ['retrieval_eligibility', 'source_extraction_and_support']) {
+      posture[key].result = 'qualified';
+      posture[key].coverage_status = coverage.coverage_status;
+    }
+  }
   return {
     total: findings.length,
     deterministic_observations: deterministic,
@@ -58,15 +72,22 @@ export function summarize(findings, { detectorsRun = [], detectorsSkipped = [],
     by_severity: bySeverity,
     by_namespace: byNamespace,
     by_discipline: byDiscipline,
-    posture: {
-      retrieval_eligibility: readinessPosture(findings, detectorsRun, detectorsSkipped, RETRIEVAL_NAMESPACES),
-      source_extraction_and_support: readinessPosture(findings, detectorsRun, detectorsSkipped, SOURCE_NAMESPACES),
-      observed_citation_behavior: citationPosture(promptResults, targetOrigin),
-    },
+    coverage: coverage ? {
+      status: coverage.coverage_status,
+      populations: coverage.populations,
+      stop_reason: coverage.stop_reason,
+    } : null,
+    posture,
   };
 }
 
-export function renderMarkdownReport({ findings, manifest, summary, detectorsSkipped = [] }) {
+export function renderMarkdownReport({ findings, manifest, summary, detectorsSkipped = [], coverage = null, verifiedRun = null }) {
+  // Only the verified loader can establish package integrity. Manifest flags
+  // are part of the package input and therefore cannot establish their own
+  // trustworthiness when this renderer is called directly.
+  const packageVerified = verifiedRun?.verified === true
+    && verifiedRun?.integrity_mode === 'sealed'
+    && typeof verifiedRun?.verification_version === 'string';
   const lines = [];
   lines.push(`# Citable audit report`);
   lines.push('');
@@ -85,10 +106,18 @@ export function renderMarkdownReport({ findings, manifest, summary, detectorsSki
   lines.push(`| Total findings | ${summary.total} |`);
   lines.push(`| Deterministic observations | ${summary.deterministic_observations} |`);
   lines.push(`| Heuristic / semantic findings | ${summary.semantic_or_heuristic} |`);
+  if (coverage) {
+    lines.push(`| Coverage status | ${coverage.coverage_status} |`);
+    lines.push(`| Evaluated resources | ${coverage.populations.evaluated} of ${coverage.populations.discovered - coverage.populations.excluded} eligible |`);
+  }
   for (const [sev, n] of Object.entries(summary.by_severity).sort((a, b) => SEV_ORDER[a[0]] - SEV_ORDER[b[0]])) {
     lines.push(`| ${sev} | ${n} |`);
   }
   lines.push('');
+  if (coverage && coverage.coverage_status !== 'complete') {
+    lines.push(`> Coverage status: **${coverage.coverage_status}**. This report describes the observed corpus and does not establish a complete site-wide determination.`);
+    lines.push('');
+  }
   lines.push('## Separate eligibility and observation states');
   lines.push('');
   lines.push('| Dimension | Result | Evidence |');
@@ -132,8 +161,26 @@ export function renderMarkdownReport({ findings, manifest, summary, detectorsSki
     lines.push('');
   }
   if (findings.length === 0) {
-    lines.push(`No findings from the executed detectors. Absence of findings is not proof of eligibility — see skipped and incomplete checks above.`);
+    const population = coverage?.populations?.evaluated ?? 0;
+    lines.push(population > 0
+      ? `No findings were produced for the ${population} successfully evaluated resource(s). Absence of findings is not proof of eligibility — see skipped and incomplete checks above.`
+      : evidenceScopeStatement({
+        coverage_status: coverage?.coverage_status || 'indeterminate',
+        determination_status: summary?.posture?.source_extraction_and_support?.result === 'pass' ? 'supported' : 'indeterminate',
+        evaluated: 0,
+        eligible: coverage?.populations?.eligible ?? 0,
+        legacy: !coverage,
+      }));
     lines.push('');
   }
-  return lines.join('\n');
+  const rendered = lines.join('\n');
+  assertEpistemicLanguage(rendered, {
+    coverage_status: coverage?.coverage_status || 'indeterminate',
+    determination_status: coverage?.coverage_status === 'complete' ? 'supported' : 'indeterminate',
+    evaluated: coverage?.populations?.evaluated ?? 0,
+    eligible: coverage?.populations?.eligible ?? 0,
+    package_verified: packageVerified,
+    legacy: verifiedRun?.legacy === true || !coverage,
+  });
+  return rendered;
 }

package/src/shared/epistemicLanguage.js

@@ -0,0 +1,86 @@
+/**
+ * Helpers for keeping presentation language within the scope of its evidence.
+ *
+ * These checks intentionally target assurance phrases, rather than individual
+ * words such as `complete` or `verified` which are also legitimate schema and
+ * lifecycle states.  A report may say that a package is checksum-verified or
+ * that a collection completed; it may not turn that fact into an unsupported
+ * corpus-wide assurance.
+ */
+
+const UNSUPPORTED_ASSURANCE_PATTERNS = Object.freeze([
+  /\ball\s+(?:conversion\s+pathways|pages?|resources?|checks?|findings?).{0,40}\b(?:verified|clean|passed|complete)\b/i,
+  /\b(?:verified[- ]clean|clean\s+and\s+verified|no\s+issues)\b/i,
+  /\b100%\s+(?:clean|verified|complete|pass(?:ed)?|coverage|conversion|funnel)/i,
+  /\b(?:site[- ]wide|entire\s+(?:site|corpus|population))\s+(?:clean|verified|complete|resolved|no\s+issues)/i,
+  /\b(?:all|entire)\s+(?:site|corpus|population)\s+(?:passed|verified|clean|complete)\b/i,
+  /(?:^|\n)\s*(?:verified|clean|resolved|optimal|complete|site[- ]wide|entire|none|all|passed)\b/im,
+  /<(?:h[1-6]|span|strong|div)[^>]*>\s*(?:verified|clean|resolved|optimal|complete|site[- ]wide|entire|none|all|passed)\b/i,
+]);
+
+function normaliseContext(context = {}) {
+  const coverage = context.coverage_status || context.coverageStatus || 'indeterminate';
+  const determination = context.determination_status || context.determinationStatus || 'indeterminate';
+  const evaluated = Number.isInteger(context.evaluated) ? context.evaluated : null;
+  const eligible = Number.isInteger(context.eligible) ? context.eligible : null;
+  const packageVerified = context.package_verified ?? context.packageVerified ?? false;
+  const legacy = context.legacy === true || context.integrity_mode === 'legacy_unverified';
+  return { coverage, determination, evaluated, eligible, packageVerified, legacy };
+}
+
+export function hasVerifiedEvidenceScope(context = {}) {
+  const state = normaliseContext(context);
+  return state.packageVerified === true
+    && context.integrity_mode === 'sealed'
+    && !state.legacy
+    && state.coverage === 'complete'
+    && state.determination === 'supported'
+    && Number.isInteger(state.evaluated)
+    && Number.isInteger(state.eligible)
+    && state.evaluated > 0
+    && state.eligible > 0
+    && state.evaluated === state.eligible;
+}
+
+/**
+ * Find assurance phrases that are unsafe for a presentation context.
+ * Complete, supported, verified packages may use the phrases when the caller
+ * supplies an explicit population; incomplete/legacy/empty evidence may not.
+ */
+export function findEpistemicLanguageViolations(text, context = {}) {
+  const value = String(text ?? '');
+  const state = normaliseContext(context);
+  const cannotClaimCorpus = !hasVerifiedEvidenceScope(context);
+  if (!cannotClaimCorpus) return [];
+  return UNSUPPORTED_ASSURANCE_PATTERNS
+    .map((pattern) => {
+      const match = value.match(pattern);
+      return match ? { phrase: match[0], index: match.index ?? 0, pattern: pattern.source } : null;
+    })
+    .filter(Boolean);
+}
+
+export function assertEpistemicLanguage(text, context = {}) {
+  const violations = findEpistemicLanguageViolations(text, context);
+  if (violations.length) {
+    throw new Error(`unsupported assurance language: ${violations.map((item) => item.phrase).join('; ')}`);
+  }
+  return text;
+}
+
+/** A short, reusable disclosure for reports and machine-readable exports. */
+export function evidenceScopeStatement(context = {}) {
+  const state = normaliseContext(context);
+  if (state.evaluated === 0 || state.eligible === 0) {
+    return 'No determination is available because no eligible resource was evaluated.';
+  }
+  if (state.coverage !== 'complete' || state.determination !== 'supported' || state.legacy || !state.packageVerified) {
+    const population = state.evaluated == null ? 'the evaluated subset' : `${state.evaluated} evaluated resource(s)`;
+    const denominator = state.eligible == null ? '' : ` of ${state.eligible} eligible`;
+    return `Coverage is ${state.coverage}; this statement applies only to ${population}${denominator}. Corpus-wide absence or cleanliness is not established.`;
+  }
+  const population = state.evaluated == null ? 'the evaluated population' : `${state.evaluated} evaluated resource(s)`;
+  return `This statement applies to ${population} under the supported evidence contract.`;
+}
+
+export const EPISTEMIC_LANGUAGE_PATTERNS = UNSUPPORTED_ASSURANCE_PATTERNS;

package/src/shared/evidenceSourceResolver.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { readJson, sha256, sha256File } from './io.js';
-import { verifyRunPackage, RunVerificationError } from './runPackageVerifier.js';
+import { readJson, sha256 } from './io.js';
+import { loadVerifiedRun } from './verifiedRunLoader.js';
 import { buildContext } from '../commands/context.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors, indexTargets } from '../detectors/framework.js';
@@ -161,6 +161,12 @@ export async function resolveEvidenceSource(root, options = {}) {
       integrity_hash: sha256(findingsJson),
       generation_mode: generationMode,
       run_metadata: null,
+      package_verified: false,
+      integrity_mode: 'in_memory_unsealed',
+      legacy: false,
+      coverage: null,
+      coverage_status: 'indeterminate',
+      determination_status: 'indeterminate',
     };
   }
 
@@ -177,10 +183,14 @@ export async function resolveEvidenceSource(root, options = {}) {
     }
 
     try {
-      const verification = verifyRunPackage(runPath, {
-        requireFindings: true,
-        requireCompleted: generationMode === 'CONTRACTUAL',
-        requireChecksums: true,
+      // Historical packages are explicitly opened in legacy mode until all
+      // producers persist coverage.json. The loader still verifies the sealed
+      // package and marks their coverage indeterminate; it never invents a
+      // complete corpus.
+      const verification = loadVerifiedRun(runPath, {
+        requireCompletedExecution: generationMode === 'CONTRACTUAL',
+        allowLegacy: true,
+        requireCoverage: false,
       });
 
       return {
@@ -188,16 +198,19 @@ export async function resolveEvidenceSource(root, options = {}) {
         source_identifier: runId,
         findings: verification.findings,
         findings_count: verification.findingsCount,
-        integrity_hash: sha256File(findPath),
+        integrity_hash: verification.package_hash,
         generation_mode: generationMode,
         run_metadata: verification.manifest,
         checksums_verified: verification.checksumsVerified,
+        package_verified: verification.verified === true && verification.integrity_mode === 'sealed',
+        integrity_mode: verification.integrity_mode,
+        legacy: verification.legacy === true,
+        coverage: verification.coverage,
+        coverage_status: verification.coverage_status,
+        determination_status: verification.determination_status,
       };
     } catch (err) {
-      if (err instanceof RunVerificationError) {
-        throw new FindingsInvalidError(runId, err.message);
-      }
-      throw err;
+      throw new FindingsInvalidError(runId, err.message);
     }
   }
 
@@ -225,6 +238,12 @@ export async function resolveEvidenceSource(root, options = {}) {
         generation_mode: generationMode,
         run_metadata: null,
         context: ctx,
+        package_verified: false,
+        integrity_mode: 'live_unsealed',
+        legacy: false,
+        coverage: ctx.coverage || null,
+        coverage_status: ctx.coverage?.coverage_status || 'indeterminate',
+        determination_status: ctx.coverage?.determination_status || 'indeterminate',
       };
     } catch (err) {
       throw new LiveInspectionFailedError(target, err.message);
@@ -243,12 +262,11 @@ export async function resolveEvidenceSource(root, options = {}) {
       const sorted = sortRunCandidatesChronologically(runsDir, candidateDirs);
       for (const candidateId of sorted) {
         const runPath = path.join(runsDir, candidateId);
-        const findPath = path.join(runPath, 'findings.json');
         try {
-          const verification = verifyRunPackage(runPath, {
-            requireFindings: true,
-            requireCompleted: false, // allow non-completed in discovery if valid
-            requireChecksums: false,
+          const verification = loadVerifiedRun(runPath, {
+            requireCompletedExecution: false,
+            allowLegacy: true,
+            requireCoverage: false,
           });
 
           return {
@@ -256,9 +274,16 @@ export async function resolveEvidenceSource(root, options = {}) {
             source_identifier: candidateId,
             findings: verification.findings,
             findings_count: verification.findingsCount,
-            integrity_hash: sha256File(findPath),
+            integrity_hash: verification.package_hash,
             generation_mode: generationMode,
             run_metadata: verification.manifest,
+            checksums_verified: verification.checksumsVerified,
+            package_verified: verification.verified === true && verification.integrity_mode === 'sealed',
+            integrity_mode: verification.integrity_mode,
+            legacy: verification.legacy === true,
+            coverage: verification.coverage,
+            coverage_status: verification.coverage_status,
+            determination_status: verification.determination_status,
           };
         } catch {
           // Try next candidate
@@ -278,6 +303,12 @@ export async function resolveEvidenceSource(root, options = {}) {
       integrity_hash: null,
       generation_mode: 'NON_CONTRACTUAL_SAMPLE',
       run_metadata: null,
+      package_verified: false,
+      integrity_mode: 'sample_unverified',
+      legacy: false,
+      coverage: null,
+      coverage_status: 'indeterminate',
+      determination_status: 'indeterminate',
     };
   }
 

package/src/shared/htmlEscape.js

@@ -26,7 +26,7 @@ export function escapeHtmlAttr(str) {
   return escapeHtml(str);
 }
 
-const SAFE_PROTOCOLS = new Set(['http:', 'https:', 'mailto:']);
+const SAFE_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'ftp:']);
 
 export function sanitizeUrl(urlStr, fallback = '#') {
   if (!urlStr || typeof urlStr !== 'string') return fallback;
@@ -38,11 +38,15 @@ export function sanitizeUrl(urlStr, fallback = '#') {
   try {
     const parsed = new URL(trimmed);
     if (SAFE_PROTOCOLS.has(parsed.protocol)) {
-      return escapeHtmlAttr(trimmed);
+      // Additional substring sanitization: ensure no CRLF injection via encoded newlines
+      const normalized = parsed.href.replace(/\r\n|\r/g, '\n');
+      return escapeHtmlAttr(normalized);
     }
-    return fallback;
+    // Unsafe protocol: return fully sanitized fallback
+    return escapeHtmlAttr(fallback);
   } catch {
-    return fallback;
+    // Invalid URL: return sanitized fallback
+    return escapeHtmlAttr(fallback);
   }
 }