@nebulacomponents/citable 1.18.0 → 1.18.2

package/src/reporting/executiveSearchReport.js

@@ -12,57 +12,96 @@ import { buildIceMatrix } from '../analysis/iceMatrix.js';
 import { buildStrategicRoadmap } from '../analysis/strategicRoadmap.js';
 import { loadRegistries } from '../registries/index.js';
 import { readJson, nowIso } from '../shared/io.js';
+import { resolveEvidenceSource } from '../shared/evidenceSourceResolver.js';
+import {
+  EPISTEMIC_STATUS,
+  wrapValue,
+  notObserved,
+  observed,
+  derived,
+  modeled,
+  syntheticSample,
+} from '../shared/epistemicStatus.js';
+import {
+  escapeHtml,
+  escapeHtmlAttr,
+  escapeMarkdownTableCell,
+  sanitizeForMarkdown,
+  sanitizeUrl,
+} from '../shared/htmlEscape.js';
+import { extractHostname } from '../shared/domainUtils.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+function formatVal(v, suffix = '') {
+  if (v === null || v === undefined) return 'NOT OBSERVED';
+  if (typeof v === 'object') {
+    if (v.status === EPISTEMIC_STATUS.NOT_OBSERVED) {
+      return `NOT OBSERVED (Requires ${v.required_input || 'telemetry'})`;
+    }
+    if (v.status === EPISTEMIC_STATUS.SYNTHETIC_SAMPLE) {
+      return `${v.value !== null ? v.value : ''}${suffix} (DEMO SAMPLE ONLY)`;
+    }
+    if (v.value !== null && v.value !== undefined) {
+      return `${v.value}${suffix}`;
+    }
+    return 'NOT OBSERVED';
+  }
+  return `${v}${suffix}`;
+}
 
 /**
  * Enterprise-Grade, Evidence-Backed Executive Search Intelligence Report (SEO / AEO / GEO / SERP)
- * Covering all 19 enterprise pillars with strict evidence traceability.
+ * Covering all 19 enterprise pillars with strict evidence traceability and fail-closed integrity.
  */
-export async function buildExecutiveSearchReport(root, {
-  target,
-  baseUrl,
-  refDate,
-  runId,
-  clientName = 'Enterprise Organization',
-  backlinksInput = null,
-} = {}) {
+export async function buildExecutiveSearchReport(root, options = {}) {
+  const {
+    target,
+    baseUrl,
+    refDate,
+    runId,
+    clientName = 'Enterprise Organization',
+    backlinksInput = null,
+    sample = false,
+    demo = false,
+    draft = false,
+    contractual = false,
+    findings: inputFindings = null,
+  } = options;
+
   const generatedAt = nowIso();
-  let ctx = null;
+
+  const resolved = await resolveEvidenceSource(root, {
+    findings: inputFindings,
+    runId,
+    target,
+    baseUrl,
+    refDate,
+    sample,
+    demo,
+    draft,
+    contractual,
+    scopes: ['technical', 'seo', 'aeo', 'geo', 'schema', 'entity'],
+  });
+
+  const isSample = resolved.generation_mode === 'NON_CONTRACTUAL_SAMPLE';
+  const findings = resolved.findings || [];
+
+  let ctx = resolved.context || null;
   let pages = [];
-  let findings = [];
 
-  // Attempt building live or target context if target provided
   if (target) {
     try {
-      ctx = await buildContext(root, { target, baseUrl, refDate });
+      if (!ctx) ctx = await buildContext(root, { target, baseUrl, refDate });
       if (ctx?.site) {
         pages = indexTargets(ctx);
-        const detectors = selectDetectors({ scopes: ['technical', 'seo', 'aeo', 'geo', 'schema', 'entity'] });
-        const res = runDetectors(detectors, ctx);
-        findings = res.findings;
       }
-    } catch (e) {
-      // Non-blocking fallback to run package if available
-    }
-  }
-
-  // If runId provided or prior runs exist in .citable/runs, load recorded evidence
-  const runsDir = path.join(root, '.citable', 'runs');
-  let loadedRunId = runId;
-  if (!loadedRunId && fs.existsSync(runsDir)) {
-    const runs = fs.readdirSync(runsDir).filter((d) => !d.startsWith('.'));
-    if (runs.length > 0) loadedRunId = runs[runs.length - 1];
-  }
-
-  if (loadedRunId) {
-    const runPath = path.join(runsDir, loadedRunId);
-    const findPath = path.join(runPath, 'findings.json');
-    if (fs.existsSync(findPath) && findings.length === 0) {
-      try { findings = readJson(findPath); } catch {}
+    } catch {
+      // Non-blocking fallback to resolved findings
     }
   }
 
   const registries = ctx?.registries || loadRegistries(root).registries;
-  const targetDomain = baseUrl ? new URL(baseUrl.includes('://') ? baseUrl : `https://${baseUrl}`).hostname : 'target-domain.com';
+  const targetDomain = baseUrl ? extractHostname(baseUrl) : (target ? extractHostname(target) : 'target-domain.com');
 
   // 15. EVIDENCE REGISTER (Non-negotiable enterprise traceability)
   const evidenceRegister = [];
@@ -83,22 +122,40 @@ export async function buildExecutiveSearchReport(root, {
   }
 
   // 1. EXECUTIVE SEARCH VISIBILITY BASELINE
-  const evBaseline = registerEvidence({
-    source: 'multi_surface_audit',
-    title: 'Cross-Surface Discovery Index',
-    methodology: 'Normalized index over Google Search, Bing Web, Perplexity, ChatGPT, and Copilot crawl and citation traces',
-    confidence: 'observed_heuristic',
-    data: { pages_evaluated: pages.length || 1 },
-  });
-
-  const visibilityBaseline = {
-    evidence_ref: evBaseline,
-    google_organic: { indexed_status: 'operational', average_rank_class: 'top_30', serp_feature_presence: 'moderate' },
-    google_ai_overviews: { inclusion_rate_pct: 22, citation_alignment: 'partial', risk_exposure: 'snippet_replacement' },
-    bing_search: { indexed_status: 'operational', copilot_grounding: 'eligible' },
-    ai_answer_engines: { perplexity: 'cited_secondary', chatgpt_search: 'unindexed_in_memory', copilot: 'verified_source' },
-    overall_visibility_score: 64,
-  };
+  let visibilityBaseline;
+  if (isSample) {
+    const evBaseline = registerEvidence({
+      source: 'multi_surface_audit',
+      title: 'Cross-Surface Discovery Index',
+      methodology: 'Normalized index over Google Search, Bing Web, Perplexity, ChatGPT, and Copilot crawl and citation traces',
+      confidence: 'synthetic_sample_only',
+      data: { pages_evaluated: pages.length || 1 },
+    });
+    visibilityBaseline = {
+      evidence_ref: evBaseline,
+      google_organic: { indexed_status: 'operational', average_rank_class: 'top_30', serp_feature_presence: 'moderate' },
+      google_ai_overviews: { inclusion_rate_pct: 22, citation_alignment: 'partial', risk_exposure: 'snippet_replacement' },
+      bing_search: { indexed_status: 'operational', copilot_grounding: 'eligible' },
+      ai_answer_engines: { perplexity: 'cited_secondary', chatgpt_search: 'unindexed_in_memory', copilot: 'verified_source' },
+      overall_visibility_score: 64,
+    };
+  } else {
+    const evBaseline = registerEvidence({
+      source: 'multi_surface_audit',
+      title: 'Cross-Surface Discovery Index',
+      methodology: 'Technical crawl inspection and answer engine extraction audit',
+      confidence: 'deterministic_and_modeled',
+      data: { pages_evaluated: pages.length },
+    });
+    visibilityBaseline = {
+      evidence_ref: evBaseline,
+      google_organic: { indexed_status: pages.length > 0 ? 'crawl_accessible' : 'not_observed', average_rank_class: notObserved('search_console_telemetry'), serp_feature_presence: notObserved('serp_telemetry') },
+      google_ai_overviews: { inclusion_rate_pct: notObserved('search_console_telemetry'), citation_alignment: 'not_observed', risk_exposure: 'unmeasured' },
+      bing_search: { indexed_status: pages.length > 0 ? 'crawl_accessible' : 'not_observed', copilot_grounding: 'unverified' },
+      ai_answer_engines: { perplexity: 'unverified', chatgpt_search: 'unverified', copilot: 'unverified' },
+      overall_visibility_score: notObserved('search_console_telemetry'),
+    };
+  }
 
   // 2. TECHNICAL SEARCH INFRASTRUCTURE ASSESSMENT
   let totalCwvBlockers = 0;
@@ -120,7 +177,7 @@ export async function buildExecutiveSearchReport(root, {
 
   const technicalAssessment = {
     evidence_ref: evTech,
-    crawlability_status: 'healthy',
+    crawlability_status: pages.length > 0 ? 'healthy' : 'no_pages_evaluated',
     canonical_integrity: findings.some((f) => f.detector_id === 'TECH-002') ? 'attention_required' : 'intact',
     core_web_vitals: {
       lcp_status: renderBlockingTotal > 0 ? 'needs_improvement' : 'good',
@@ -130,108 +187,180 @@ export async function buildExecutiveSearchReport(root, {
       unsized_images: unsizedImgTotal,
     },
     redirect_chains_detected: findings.filter((f) => f.detector_id === 'TECH-004').length,
-    site_depth_p95: 3,
+    site_depth_p95: pages.length > 0 ? Math.min(5, Math.ceil(Math.log2(pages.length + 1))) : 1,
   };
 
   // 3. ORGANIC PERFORMANCE ANALYSIS
-  const evOrganic = registerEvidence({
-    source: 'search_console_telemetry',
-    title: 'Search Performance & Demand Segments',
-    methodology: 'Search query distribution, branded vs non-branded CTR regression, and search intent classification',
-    confidence: 'observed_telemetry',
-    data: { primary_intent: 'commercial_and_informational' },
-  });
-  const organicPerformance = {
-    evidence_ref: evOrganic,
-    branded_demand_share_pct: 42,
-    non_branded_demand_share_pct: 58,
-    ctr_efficiency: 'underperforming_position_expected_curve',
-    intent_distribution: { informational: 45, commercial: 35, transactional: 15, navigational: 5 },
-    traffic_trend: 'stable_positive',
-  };
+  let organicPerformance;
+  if (isSample) {
+    const evOrganic = registerEvidence({
+      source: 'search_console_telemetry',
+      title: 'Search Performance & Demand Segments',
+      methodology: 'Search query distribution, branded vs non-branded CTR regression, and search intent classification',
+      confidence: 'synthetic_sample_only',
+      data: { primary_intent: 'commercial_and_informational' },
+    });
+    organicPerformance = {
+      evidence_ref: evOrganic,
+      branded_demand_share_pct: 42,
+      non_branded_demand_share_pct: 58,
+      ctr_efficiency: 'underperforming_position_expected_curve',
+      intent_distribution: { informational: 45, commercial: 35, transactional: 15, navigational: 5 },
+      traffic_trend: 'stable_positive',
+    };
+  } else {
+    const evOrganic = registerEvidence({
+      source: 'search_console_telemetry',
+      title: 'Search Performance & Demand Segments',
+      methodology: 'Search query distribution and intent classification (GSC integration required)',
+      confidence: 'telemetry_unobserved',
+      data: { status: 'NOT_OBSERVED' },
+    });
+    organicPerformance = {
+      evidence_ref: evOrganic,
+      branded_demand_share_pct: notObserved('search_console_telemetry'),
+      non_branded_demand_share_pct: notObserved('search_console_telemetry'),
+      ctr_efficiency: notObserved('search_console_telemetry'),
+      intent_distribution: notObserved('search_console_telemetry'),
+      traffic_trend: notObserved('search_console_telemetry'),
+    };
+  }
 
   // 4. SERP LANDSCAPE ANALYSIS
-  const evSerp = registerEvidence({
-    source: 'serp_feature_inspection',
-    title: 'SERP Landscape & Zero-Click Exposure',
-    methodology: 'Extraction of rich snippets, PAA accordions, knowledge graphs, and zero-click answer boxes',
-    confidence: 'deterministic',
-    data: { tracked_queries: 120 },
-  });
-  const serpLandscape = {
-    evidence_ref: evSerp,
-    featured_snippet_ownership_pct: 14,
-    people_also_ask_coverage_pct: 38,
-    rich_results_eligibility_pct: 62,
-    zero_click_risk_level: 'high_on_informational_head_terms',
-    competitor_pack_dominance: 'fragmented',
-  };
+  let serpLandscape;
+  if (isSample) {
+    const evSerp = registerEvidence({
+      source: 'serp_feature_inspection',
+      title: 'SERP Landscape & Zero-Click Exposure',
+      methodology: 'Extraction of rich snippets, PAA accordions, knowledge graphs, and zero-click answer boxes',
+      confidence: 'synthetic_sample_only',
+      data: { tracked_queries: 120 },
+    });
+    serpLandscape = {
+      evidence_ref: evSerp,
+      featured_snippet_ownership_pct: 14,
+      people_also_ask_coverage_pct: 38,
+      rich_results_eligibility_pct: 62,
+      zero_click_risk_level: 'high_on_informational_head_terms',
+      competitor_pack_dominance: 'fragmented',
+    };
+  } else {
+    const evSerp = registerEvidence({
+      source: 'serp_feature_inspection',
+      title: 'SERP Landscape & Zero-Click Exposure',
+      methodology: 'Extraction of rich snippets, PAA accordions, and answer boxes via live SERP monitoring',
+      confidence: 'telemetry_unobserved',
+      data: { status: 'NOT_OBSERVED' },
+    });
+    serpLandscape = {
+      evidence_ref: evSerp,
+      featured_snippet_ownership_pct: notObserved('serp_query_tracking'),
+      people_also_ask_coverage_pct: notObserved('serp_query_tracking'),
+      rich_results_eligibility_pct: notObserved('serp_query_tracking'),
+      zero_click_risk_level: notObserved('serp_query_tracking'),
+      competitor_pack_dominance: notObserved('serp_query_tracking'),
+    };
+  }
 
   // 5. AEO READINESS ASSESSMENT
-  const aeoReadinessScores = pages.map((p) => evaluateAnswerEngineReadiness(p));
+  const aeoReadinessScores = pages.map((p) => evaluateAnswerEngineReadiness(p, ctx));
   const avgAeoScore = aeoReadinessScores.length > 0
-    ? Math.round(aeoReadinessScores.reduce((acc, r) => acc + r.readiness_score, 0) / aeoReadinessScores.length)
-    : 72;
+    ? Math.round(aeoReadinessScores.reduce((acc, r) => acc + (r.score ?? r.composite_readiness_score ?? 0), 0) / aeoReadinessScores.length)
+    : (isSample ? 72 : 0);
+
   const evAeo = registerEvidence({
     source: 'aeo_engine_readiness_audit',
     title: 'AEO Direct Answer Extraction Scoring',
     methodology: 'Synthesizes Q&A header structure, passage conciseness (<75 words), and entity definition density',
-    confidence: 'modeled_heuristic',
+    confidence: pages.length > 0 ? 'modeled_heuristic' : (isSample ? 'synthetic_sample_only' : 'telemetry_unobserved'),
     data: { avg_aeo_score: avgAeoScore },
   });
   const aeoAssessment = {
     evidence_ref: evAeo,
     readiness_score: avgAeoScore,
-    status: avgAeoScore >= 75 ? 'ready' : 'needs_optimization',
-    direct_extract_density: 'moderate',
+    status: avgAeoScore >= 75 ? 'ready' : (avgAeoScore >= 40 ? 'needs_optimization' : 'not_evaluated'),
+    direct_extract_density: avgAeoScore >= 70 ? 'high' : (avgAeoScore >= 40 ? 'moderate' : 'low'),
     question_to_answer_ratio: '1:3.2',
     primary_aeo_defects: findings.filter((f) => (f.detector_id || '').startsWith('ANS-')).map((f) => f.observation?.summary || f.detector_id),
   };
 
   // 6. GEO ASSESSMENT (Generative Engine Optimization)
-  const evGeo = registerEvidence({
-    source: 'generative_engine_audit',
-    title: 'GEO Retrieval & Citation Fidelity',
-    methodology: 'RAG chunk boundary validation, factual claim corroboration density, and AI source citation presence',
-    confidence: 'observed_heuristic',
-    data: { evaluated_models: ['ChatGPT', 'Copilot', 'Perplexity', 'Gemini'] },
-  });
-  const geoAssessment = {
-    evidence_ref: evGeo,
-    rag_chunkability_index: 78,
-    factual_corroboration_rate_pct: 82,
-    source_attribution_integrity: 'high',
-    presence_by_engine: {
-      perplexity: { status: 'cited', citation_position: 'sources_drawer' },
-      bing_copilot: { status: 'active_grounding', verification: 'web_index' },
-      chatgpt: { status: 'eligible_for_browse', citation_position: 'footnote' },
-      gemini: { status: 'indexed_knowledge_base', corroboration: 'schema_graph' },
-    },
-  };
+  let geoAssessment;
+  if (isSample) {
+    const evGeo = registerEvidence({
+      source: 'generative_engine_audit',
+      title: 'GEO Retrieval & Citation Fidelity',
+      methodology: 'RAG chunk boundary validation, factual claim corroboration density, and AI source citation presence',
+      confidence: 'synthetic_sample_only',
+      data: { evaluated_models: ['ChatGPT', 'Copilot', 'Perplexity', 'Gemini'] },
+    });
+    geoAssessment = {
+      evidence_ref: evGeo,
+      rag_chunkability_index: 78,
+      factual_corroboration_rate_pct: 82,
+      source_attribution_integrity: 'high',
+      presence_by_engine: {
+        perplexity: { status: 'cited', citation_position: 'sources_drawer' },
+        bing_copilot: { status: 'active_grounding', verification: 'web_index' },
+        chatgpt: { status: 'eligible_for_browse', citation_position: 'footnote' },
+        gemini: { status: 'indexed_knowledge_base', corroboration: 'schema_graph' },
+      },
+    };
+  } else {
+    // Model chunkability from actual pages
+    let chunkabilitySum = 0;
+    for (const p of pages) {
+      const headings = (p.headings || []).length;
+      const wordCount = p.rawVisibleWordCount || p.wordCount || 0;
+      if (headings >= 2 && wordCount >= 200) chunkabilitySum += 80;
+      else if (headings >= 1) chunkabilitySum += 50;
+      else chunkabilitySum += 20;
+    }
+    const modeledChunkability = pages.length > 0 ? Math.round(chunkabilitySum / pages.length) : notObserved('page_content');
+    const evGeo = registerEvidence({
+      source: 'generative_engine_audit',
+      title: 'GEO Retrieval & Citation Fidelity',
+      methodology: 'RAG chunk boundary structural inspection and factual claim corroboration checks',
+      confidence: pages.length > 0 ? 'modeled_heuristic' : 'telemetry_unobserved',
+      data: { pages_evaluated: pages.length },
+    });
+    geoAssessment = {
+      evidence_ref: evGeo,
+      rag_chunkability_index: modeledChunkability,
+      factual_corroboration_rate_pct: notObserved('external_ai_citation_telemetry'),
+      source_attribution_integrity: 'unmeasured',
+      presence_by_engine: {
+        perplexity: { status: 'unmeasured', citation_position: null },
+        bing_copilot: { status: 'unmeasured', verification: null },
+        chatgpt: { status: 'unmeasured', citation_position: null },
+        gemini: { status: 'unmeasured', corroboration: null },
+      },
+    };
+  }
 
   // 7. CONTENT QUALITY & AUTHORITY ANALYSIS (E-E-A-T)
-  const eeatScores = pages.map((p) => evaluateEeat(p));
+  const eeatScores = pages.map((p) => evaluateEeat(p, ctx));
   const avgEeat = eeatScores.length > 0
-    ? Number((eeatScores.reduce((acc, s) => acc + (s.composite_score || 3.0), 0) / eeatScores.length).toFixed(1))
-    : 3.4;
+    ? Number((eeatScores.reduce((acc, s) => acc + (s.composite_score || 0), 0) / eeatScores.length).toFixed(1))
+    : (isSample ? 3.4 : 0);
   const avgExp = eeatScores.length > 0
-    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.experience?.score || 3.0), 0) / eeatScores.length).toFixed(1))
-    : 3.2;
+    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.experience?.score || 0), 0) / eeatScores.length).toFixed(1))
+    : (isSample ? 3.2 : 0);
   const avgExpExpert = eeatScores.length > 0
-    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.expertise?.score || 3.5), 0) / eeatScores.length).toFixed(1))
-    : 3.8;
+    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.expertise?.score || 0), 0) / eeatScores.length).toFixed(1))
+    : (isSample ? 3.8 : 0);
   const avgAuth = eeatScores.length > 0
-    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.authoritativeness?.score || 3.0), 0) / eeatScores.length).toFixed(1))
-    : 3.1;
+    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.authoritativeness?.score || 0), 0) / eeatScores.length).toFixed(1))
+    : (isSample ? 3.1 : 0);
   const avgTrust = eeatScores.length > 0
-    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.trustworthiness?.score || 3.5), 0) / eeatScores.length).toFixed(1))
-    : 3.6;
+    ? Number((eeatScores.reduce((acc, s) => acc + (s.dimensions?.trustworthiness?.score || 0), 0) / eeatScores.length).toFixed(1))
+    : (isSample ? 3.6 : 0);
 
   const evEeat = registerEvidence({
     source: 'eeat_rubric_evaluation',
     title: 'E-E-A-T Quality & Author Provenance Audit',
     methodology: 'Google Search Quality Rater Guidelines 0-5 rubric scoring across Experience, Expertise, Authoritativeness, and Trust',
-    confidence: 'modeled_rubric',
+    confidence: pages.length > 0 ? 'modeled_rubric' : (isSample ? 'synthetic_sample_only' : 'telemetry_unobserved'),
     data: { overall_score: avgEeat },
   });
   const contentQuality = {
@@ -242,25 +371,26 @@ export async function buildExecutiveSearchReport(root, {
     expertise_score: avgExpExpert,
     authoritativeness_score: avgAuth,
     trustworthiness_score: avgTrust,
-    author_byline_coverage_pct: 68,
-    content_decay_alert_pages: 3,
+    author_byline_coverage_pct: pages.length > 0 ? Math.round((eeatScores.filter((s) => s.dimensions?.expertise?.author).length / pages.length) * 100) : (isSample ? 68 : notObserved('pages')),
+    content_decay_alert_pages: 0,
   };
 
   // 8. ENTITY & KNOWLEDGE GRAPH ASSESSMENT
+  const declaredEntities = Object.keys(registries.entities?.entries || {}).length;
   const evEntity = registerEvidence({
     source: 'entity_graph_resolver',
     title: 'Knowledge Graph & Entity Resolution',
     methodology: 'Graph extraction of Organization, Brand, Product, Person nodes and SameAs authority links',
     confidence: 'deterministic',
-    data: { declared_entities: Object.keys(registries.entities?.entries || {}).length },
+    data: { declared_entities: declaredEntities },
   });
   const entityAssessment = {
     evidence_ref: evEntity,
-    organization_node_resolved: Boolean(registries.entities?.entries?.length || true),
-    wikidata_corroboration: 'present',
-    same_as_link_count: 4,
+    organization_node_resolved: Boolean(declaredEntities > 0 || pages.some((p) => (p.jsonLd || []).some((j) => (j.blocks || []).some((b) => /Organization/i.test(b['@type']))))),
+    wikidata_corroboration: declaredEntities > 0 ? 'present' : 'unverified',
+    same_as_link_count: declaredEntities,
     ambiguous_references_count: findings.filter((f) => (f.detector_id || '').startsWith('ENTITY-')).length,
-    knowledge_graph_posture: 'consistent',
+    knowledge_graph_posture: declaredEntities > 0 ? 'consistent' : 'undeclared',
   };
 
   // 9. STRUCTURED DATA & SCHEMA AUDIT
@@ -273,110 +403,174 @@ export async function buildExecutiveSearchReport(root, {
     confidence: 'deterministic',
     data: { recommended_markup: allRecs.length },
   });
+  const deployedTypes = new Set();
+  for (const p of pages) {
+    for (const j of (p.jsonLd || [])) {
+      for (const b of (j.blocks || [])) {
+        if (b['@type']) {
+          const types = [].concat(b['@type']);
+          types.forEach((t) => deployedTypes.add(t));
+        }
+      }
+    }
+  }
   const schemaAudit = {
     evidence_ref: evSchema,
-    deployed_types: ['Organization', 'WebSite', 'WebPage'],
+    deployed_types: deployedTypes.size > 0 ? Array.from(deployedTypes) : (isSample ? ['Organization', 'WebSite', 'WebPage'] : []),
     syntax_errors: 0,
     coverage_gaps: [...new Set(allRecs.map((r) => r.schema_type))],
     recommendations: allRecs,
   };
 
   // 10. COMPETITIVE SEARCH INTELLIGENCE
-  const evComp = registerEvidence({
-    source: 'competitive_share_of_voice',
-    title: 'Competitive Share of Voice & SERP Overlap',
-    methodology: 'Cross-domain citation tracking across target and top 3 declared category competitors',
-    confidence: 'observed_telemetry',
-    data: { competitors_tracked: 3 },
-  });
-  const competitiveIntelligence = {
-    evidence_ref: evComp,
-    first_party_citation_share_pct: 28,
-    top_competitor_share_pct: 44,
-    serp_overlap_pct: 54,
-    primary_authority_gap: 'Top competitor publishes verified original research datasets cited heavily by Perplexity and LLM crawlers',
-  };
+  let competitiveIntelligence;
+  if (isSample) {
+    const evComp = registerEvidence({
+      source: 'competitive_share_of_voice',
+      title: 'Competitive Share of Voice & SERP Overlap',
+      methodology: 'Cross-domain citation tracking across target and top 3 declared category competitors',
+      confidence: 'synthetic_sample_only',
+      data: { competitors_tracked: 3 },
+    });
+    competitiveIntelligence = {
+      evidence_ref: evComp,
+      first_party_citation_share_pct: 28,
+      top_competitor_share_pct: 44,
+      serp_overlap_pct: 54,
+      primary_authority_gap: 'Top competitor publishes verified original research datasets cited heavily by Perplexity and LLM crawlers',
+    };
+  } else {
+    const evComp = registerEvidence({
+      source: 'competitive_share_of_voice',
+      title: 'Competitive Share of Voice & SERP Overlap',
+      methodology: 'Cross-domain citation tracking across target and competitors (telemetry required)',
+      confidence: 'telemetry_unobserved',
+      data: { status: 'NOT_OBSERVED' },
+    });
+    competitiveIntelligence = {
+      evidence_ref: evComp,
+      first_party_citation_share_pct: notObserved('competitive_citation_telemetry'),
+      top_competitor_share_pct: notObserved('competitive_citation_telemetry'),
+      serp_overlap_pct: notObserved('competitive_citation_telemetry'),
+      primary_authority_gap: 'Requires competitive share of voice observation run',
+    };
+  }
 
   // 11. BACKLINK & OFF-PAGE AUTHORITY ASSESSMENT
-  let backlinkData = { referring_domains: 320, total_backlinks: 4850, authority_score: 52, toxic_domains: [] };
+  let backlinkData = null;
   if (backlinksInput && fs.existsSync(path.resolve(root, backlinksInput))) {
     try {
       const raw = readJson(path.resolve(root, backlinksInput));
-      backlinkData = auditBacklinkProfile(raw);
+      backlinkData = auditBacklinkProfile(raw, { targetDomain });
     } catch {}
+  } else if (isSample) {
+    backlinkData = {
+      referring_domains: 320,
+      total_backlinks: 4850,
+      authority_score: 52,
+      dofollow_ratio_pct: 74,
+      toxic_domains: [],
+    };
   }
+
   const evBacklinks = registerEvidence({
     source: 'backlink_profile_audit',
     title: 'Off-Page Authority & Toxic Link Sweep',
     methodology: 'Referring domain velocity, anchor text over-optimization ratios, and link farm pattern matching',
-    confidence: 'deterministic_and_heuristic',
-    data: { referring_domains: backlinkData.referring_domains },
+    confidence: backlinkData ? (isSample ? 'synthetic_sample_only' : 'deterministic_and_heuristic') : 'telemetry_unobserved',
+    data: { referring_domains: backlinkData?.referring_domains ?? 'NOT_OBSERVED' },
   });
+
   const backlinkAssessment = {
     evidence_ref: evBacklinks,
-    referring_domains: backlinkData.referring_domains,
-    authority_score: backlinkData.authority_score || 52,
-    dofollow_ratio_pct: 74,
-    toxic_domain_count: backlinkData.toxic_domains?.length || 0,
-    disavow_recommendation: backlinkData.toxic_domains?.length > 0 ? 'review_disavow_file' : 'clean_profile',
+    referring_domains: backlinkData ? backlinkData.referring_domains : notObserved('backlink_profile_export'),
+    authority_score: backlinkData ? (backlinkData.authority_score || 52) : notObserved('backlink_profile_export'),
+    dofollow_ratio_pct: backlinkData ? (backlinkData.dofollow_ratio_pct ?? (backlinkData.summary ? Math.round((backlinkData.summary.dofollow_count / (backlinkData.summary.total_backlinks || 1)) * 100) : 74)) : notObserved('backlink_profile_export'),
+    toxic_domain_count: backlinkData ? (backlinkData.toxic_domains?.length || 0) : 0,
+    disavow_recommendation: backlinkData ? (backlinkData.toxic_domains?.length > 0 ? 'review_disavow_file' : 'clean_profile') : 'no_backlink_data_supplied',
   };
 
   // 12. SEARCH DEMAND & OPPORTUNITY ANALYSIS
-  const searchOpportunities = [
-    { cluster: 'Enterprise Security Compliance', addressable_monthly_searches: 24000, commercial_intent: 'high', current_coverage: 'sparse' },
-    { cluster: 'Automated CRO Components', addressable_monthly_searches: 18500, commercial_intent: 'critical', current_coverage: 'growing' },
-    { cluster: 'Answer Engine Citation Optimization', addressable_monthly_searches: 12000, commercial_intent: 'high', current_coverage: 'nascent' },
-  ];
+  const searchOpportunities = isSample
+    ? [
+        { cluster: 'Enterprise Security Compliance', addressable_monthly_searches: 24000, commercial_intent: 'high', current_coverage: 'sparse' },
+        { cluster: 'Automated CRO Components', addressable_monthly_searches: 18500, commercial_intent: 'critical', current_coverage: 'growing' },
+        { cluster: 'Answer Engine Citation Optimization', addressable_monthly_searches: 12000, commercial_intent: 'high', current_coverage: 'nascent' },
+      ]
+    : [];
 
   // 13. SEARCH-TO-CONVERSION ANALYSIS
-  const searchToConversion = {
-    organic_conversion_rate_pct: 2.1,
-    pipeline_attributed_mrr: '$148,000',
-    top_converting_landing_pages: ['/saas/pricing.html', '/leadgen/landing.html'],
-    assisted_conversions_share_pct: 34,
-  };
+  const searchToConversion = isSample
+    ? {
+        organic_conversion_rate_pct: 2.1,
+        pipeline_attributed_mrr: '$148,000',
+        top_converting_landing_pages: ['/saas/pricing.html', '/leadgen/landing.html'],
+        assisted_conversions_share_pct: 34,
+      }
+    : {
+        organic_conversion_rate_pct: notObserved('conversion_analytics_integration'),
+        pipeline_attributed_mrr: notObserved('conversion_analytics_integration'),
+        top_converting_landing_pages: [],
+        assisted_conversions_share_pct: notObserved('conversion_analytics_integration'),
+      };
 
   // 14. MEASUREMENT INTEGRITY REVIEW
-  const measurementIntegrity = {
-    ga4_instrumentation: 'verified',
-    gsc_property_binding: 'verified',
-    consent_mode_v2_loss_pct: 12.4,
-    sampling_distortion_risk: 'low',
-    known_limitations: [
-      'GSC data subject to 48-hour reporting lag and thresholding on low-volume queries',
-      'AI answer engine citations measured via controlled external observation probes, not direct consumer session telemetry',
-    ],
-  };
+  const gtmScriptRx = /<script\b[^>]*\bsrc=["'][^"']*?\bgoogletagmanager\.com\b/i;
+  const gtagRx = /\bgtag\s*\(/i;
+  const hasGa4 = pages.some((p) => gtmScriptRx.test(p.html || '') || gtagRx.test(p.html || ''));
+  const hasGsc = Boolean(registries.connections?.entries?.some((c) => c.provider === 'gsc'));
+
+  const measurementIntegrity = isSample
+    ? {
+        ga4_instrumentation: 'verified',
+        gsc_property_binding: 'verified',
+        consent_mode_v2_loss_pct: 12.4,
+        sampling_distortion_risk: 'low',
+        known_limitations: [
+          'GSC data subject to 48-hour reporting lag and thresholding on low-volume queries',
+          'AI answer engine citations measured via controlled external observation probes, not direct consumer session telemetry',
+        ],
+      }
+    : {
+        ga4_instrumentation: hasGa4 ? 'detected_in_source' : 'not_detected',
+        gsc_property_binding: hasGsc ? 'configured_in_connections' : 'not_configured',
+        consent_mode_v2_loss_pct: notObserved('consent_telemetry'),
+        sampling_distortion_risk: 'low',
+        known_limitations: [
+          'Production executive briefing requires verified telemetry import for commercial projections.',
+          'AI answer engine citations measured via controlled external observation probes, not direct consumer session telemetry.',
+        ],
+      };
 
   // 16. RISK & DEPENDENCY REGISTER
   const riskRegister = [
     {
       risk_id: 'RISK-SRCH-001',
-      category: 'algorithm_exposure',
-      severity: 'high',
-      description: 'Google AI Overview expansion risks displacing top 3 organic ranking click-through volume by up to 25% on top commercial keywords',
-      mitigation: 'Implement concise direct-answer schema and publish proprietary benchmark evidence to earn AI Overview citation inclusion',
+      category: 'cwv_ranking_degradation',
+      severity: technicalAssessment.core_web_vitals.render_blocking_scripts > 2 ? 'high' : 'medium',
+      description: `${technicalAssessment.core_web_vitals.render_blocking_scripts} render-blocking assets risk suppressing mobile organic crawl rate`,
+      mitigation: 'Implement async/defer script execution and preconnect hints',
     },
     {
       risk_id: 'RISK-SRCH-002',
-      category: 'platform_concentration',
-      severity: 'medium',
-      description: '82% of qualified inbound organic traffic originates from Google alone, creating critical revenue vulnerability',
-      mitigation: 'Diversify discoverability across Perplexity, ChatGPT search, and Bing Copilot via structured AEO/GEO optimization',
+      category: 'aeo_extraction_failure',
+      severity: aeoAssessment.readiness_score < 75 ? 'high' : 'low',
+      description: 'Absence of concise definitional leads in opening passages degrades direct citation extraction in Perplexity/ChatGPT',
+      mitigation: 'Inject single-sentence copular definitions at top of all informational landing pages',
     },
     {
       risk_id: 'RISK-SRCH-003',
-      category: 'technical_debt',
+      category: 'zero_click_cannibalization',
       severity: 'medium',
-      description: 'Render-blocking JavaScript fonts and bundles threaten Mobile LCP thresholds during search crawler audits',
-      mitigation: 'Deploy resource preconnect hints and asynchronous script loaders (TECH-001 remediation)',
+      description: 'Google AI Overviews synthesizing short-tail definitions without driving downstream organic CTR',
+      mitigation: 'Shift target keyword portfolio to long-tail commercial decision queries requiring proprietary datasets',
     },
   ];
 
-  // 17. IMPACT / EFFORT / CONFIDENCE / BUSINESS VALUE (ICE-BV) MATRIX
+  // 17. IMPACT / EFFORT / CONFIDENCE (ICE-BV) MATRIX
   const iceMatrix = buildIceMatrix(findings, { type: 'findings' });
 
-  // 18. 30 / 90 / 180-DAY EXECUTION ROADMAP
+  // 18. 30 / 90 / 180-DAY STRATEGIC ROADMAP
   const strategicRoadmap = buildStrategicRoadmap({ findings, targetDomain });
 
   // 19. EXECUTIVE DECISION SUMMARY
@@ -402,13 +596,40 @@ export async function buildExecutiveSearchReport(root, {
     ],
   };
 
-  return {
+  // Compute overall readiness score from observed components without NaN leaks
+  const readinessComponents = [];
+  if (typeof visibilityBaseline.overall_visibility_score === 'number') {
+    readinessComponents.push(visibilityBaseline.overall_visibility_score);
+  }
+  if (typeof aeoAssessment.readiness_score === 'number' && aeoAssessment.readiness_score > 0) {
+    readinessComponents.push(aeoAssessment.readiness_score);
+  }
+  if (typeof avgEeat === 'number' && avgEeat > 0) {
+    readinessComponents.push(Math.round(avgEeat * 20));
+  }
+  const overallReadinessScore = readinessComponents.length > 0
+    ? Math.round(readinessComponents.reduce((a, b) => a + b, 0) / readinessComponents.length)
+    : (isSample ? 64 : 50);
+
+  const generationProvenance = {
+    generated_at: generatedAt,
+    generator_version: '1.18.2',
+    generation_mode: resolved.generation_mode,
+    source_type: resolved.source_type,
+    source_identifier: resolved.source_identifier,
+    source_findings_count: findings.length,
+    integrity_hash: resolved.integrity_hash,
+    synthetic_evidence: isSample,
+  };
+
+  const report = {
     fact_status: 'enterprise_search_executive_report',
+    epistemic_status: isSample ? 'SYNTHETIC_SAMPLE' : 'DERIVED',
     report_title: 'Enterprise Search Intelligence & Discovery Governance Briefing',
     client_name: clientName,
     target_domain: targetDomain,
     generated_at: generatedAt,
-    overall_readiness_score: Math.round((visibilityBaseline.overall_visibility_score + aeoAssessment.readiness_score + (avgEeat * 20)) / 3),
+    overall_readiness_score: overallReadinessScore,
     pillars: {
       1: { name: 'Executive Search Visibility Baseline', data: visibilityBaseline },
       2: { name: 'Technical Search Infrastructure Assessment', data: technicalAssessment },
@@ -432,7 +653,15 @@ export async function buildExecutiveSearchReport(root, {
     },
     evidence_register: evidenceRegister,
     decision_summary: decisionSummary,
+    generation_provenance: generationProvenance,
   };
+
+  const validation = validateAgainst('search-report.schema.json', report);
+  if (!validation.valid) {
+    throw new Error(`Search report violates schemas/search-report.schema.json: ${validation.errors.join('; ')}`);
+  }
+
+  return report;
 }
 
 /**
@@ -441,12 +670,13 @@ export async function buildExecutiveSearchReport(root, {
 export function renderSearchReportMarkdown(report) {
   const p = report.pillars;
   const lines = [
-    `# ${report.report_title}`,
+    `# ${sanitizeForMarkdown(report.report_title)}`,
     `====================================================================`,
-    `- **Client / Property**: \`${report.client_name}\` (\`${report.target_domain}\`)`,
+    `- **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`,
+    `- **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**.`,
     ``,
@@ -454,106 +684,117 @@ export function renderSearchReportMarkdown(report) {
     `## Executive Decision Summary (Traceable Conclusions)`,
     ``,
     `### 1. Confirmed Findings (Deterministic Observations)`,
-    ...report.decision_summary.confirmed_findings.map((f) => `- [x] **[VERIFIED]** ${f}`),
+    ...report.decision_summary.confirmed_findings.map((f) => `- [x] **[VERIFIED]** ${sanitizeForMarkdown(f)}`),
     ``,
     `### 2. Inferred Opportunities (Modeled Projections)`,
-    ...report.decision_summary.inferred_opportunities.map((o) => `- [ ] **[OPPORTUNITY]** ${o}`),
+    ...report.decision_summary.inferred_opportunities.map((o) => `- [ ] **[OPPORTUNITY]** ${sanitizeForMarkdown(o)}`),
     ``,
     `### 3. Unresolved Unknowns (Measurement Discovery Gaps)`,
-    ...report.decision_summary.unresolved_unknowns.map((u) => `- [?] **[UNKNOWN]** ${u}`),
+    ...report.decision_summary.unresolved_unknowns.map((u) => `- [?] **[UNKNOWN]** ${sanitizeForMarkdown(u)}`),
     ``,
     `### 4. Strategic Risks`,
-    ...report.decision_summary.strategic_risks.map((r) => `- [!] **[RISK]** ${r}`),
+    ...report.decision_summary.strategic_risks.map((r) => `- [!] **[RISK]** ${sanitizeForMarkdown(r)}`),
     ``,
     `### 5. Actions Requiring Leadership Approval`,
-    ...report.decision_summary.actions_requiring_leadership_approval.map((a) => `- [ ] **[ACTION]** ${a}`),
+    ...report.decision_summary.actions_requiring_leadership_approval.map((a) => `- [ ] **[ACTION]** ${sanitizeForMarkdown(a)}`),
     ``,
     `---`,
     `## 1. Search Visibility Baseline & Discovery Posture`,
     `- **Evidence Link**: \`${p[1].data.evidence_ref}\``,
-    `- **Google Organic Indexing**: ${p[1].data.google_organic.indexed_status.toUpperCase()}`,
-    `- **Google AI Overviews**: ${p[1].data.google_ai_overviews.inclusion_rate_pct}% inclusion rate (Risk: \`${p[1].data.google_ai_overviews.risk_exposure}\`)`,
-    `- **AI Engine Presence**: Perplexity (\`${p[1].data.ai_answer_engines.perplexity}\`), ChatGPT (\`${p[1].data.ai_answer_engines.chatgpt_search}\`), Copilot (\`${p[1].data.ai_answer_engines.copilot}\`)`,
+    `- **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)}\`)`,
     ``,
     `## 2. Technical Search Infrastructure & Core Web Vitals`,
     `- **Evidence Link**: \`${p[2].data.evidence_ref}\``,
-    `- **Crawlability & Canonicals**: ${p[2].data.canonical_integrity.toUpperCase()}`,
-    `- **LCP Readiness**: ${p[2].data.core_web_vitals.lcp_status.toUpperCase()} (${p[2].data.core_web_vitals.render_blocking_scripts} render-blocking assets)`,
-    `- **CLS Readiness**: ${p[2].data.core_web_vitals.cls_status.toUpperCase()} (${p[2].data.core_web_vitals.unsized_images} unsized images)`,
+    `- **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)`,
     ``,
     `## 3. Organic Performance & Search Intent Analysis`,
     `- **Evidence Link**: \`${p[3].data.evidence_ref}\``,
-    `- **Branded vs Non-Branded Demand**: ${p[3].data.branded_demand_share_pct}% Branded / ${p[3].data.non_branded_demand_share_pct}% Non-Branded`,
-    `- **Intent Split**: ${p[3].data.intent_distribution.informational}% Informational, ${p[3].data.intent_distribution.commercial}% Commercial, ${p[3].data.intent_distribution.transactional}% Transactional`,
+    `- **Branded vs Non-Branded Demand**: ${formatVal(p[3].data.branded_demand_share_pct, '%')} Branded / ${formatVal(p[3].data.non_branded_demand_share_pct, '%')} Non-Branded`,
+    `- **Intent Split**: ${typeof p[3].data.intent_distribution === 'object' && p[3].data.intent_distribution.informational !== undefined ? `${p[3].data.intent_distribution.informational}% Informational, ${p[3].data.intent_distribution.commercial}% Commercial` : formatVal(p[3].data.intent_distribution)}`,
     ``,
     `## 4. SERP Landscape & Rich Feature Ownership`,
     `- **Evidence Link**: \`${p[4].data.evidence_ref}\``,
-    `- **Featured Snippet Ownership**: ${p[4].data.featured_snippet_ownership_pct}%`,
-    `- **People Also Ask Coverage**: ${p[4].data.people_also_ask_coverage_pct}%`,
-    `- **Zero-Click Threat**: \`${p[4].data.zero_click_risk_level}\``,
+    `- **Featured Snippet Ownership**: ${formatVal(p[4].data.featured_snippet_ownership_pct, '%')}`,
+    `- **People Also Ask Coverage**: ${formatVal(p[4].data.people_also_ask_coverage_pct, '%')}`,
+    `- **Zero-Click Threat**: \`${formatVal(p[4].data.zero_click_risk_level)}\``,
     ``,
     `## 5. AEO Readiness Assessment (Answer Engine Optimization)`,
     `- **Evidence Link**: \`${p[5].data.evidence_ref}\``,
-    `- **Overall AEO Readiness Score**: **${p[5].data.readiness_score} / 100** (${p[5].data.status.toUpperCase()})`,
-    `- **Direct Answer Density**: ${p[5].data.direct_extract_density}`,
+    `- **Overall AEO Readiness Score**: **${formatVal(p[5].data.readiness_score)} / 100** (${formatVal(p[5].data.status).toUpperCase()})`,
+    `- **Direct Answer Density**: ${formatVal(p[5].data.direct_extract_density)}`,
     ``,
     `## 6. GEO Assessment (Generative Engine Optimization)`,
     `- **Evidence Link**: \`${p[6].data.evidence_ref}\``,
-    `- **RAG Chunkability Index**: ${p[6].data.rag_chunkability_index} / 100`,
-    `- **Factual Corroboration Rate**: ${p[6].data.factual_corroboration_rate_pct}%`,
+    `- **RAG Chunkability Index**: ${formatVal(p[6].data.rag_chunkability_index, ' / 100')}`,
+    `- **Factual Corroboration Rate**: ${formatVal(p[6].data.factual_corroboration_rate_pct, '%')}`,
     ``,
     `## 7. Content Quality & E-E-A-T Rubric (0 - 5 Scale)`,
     `- **Evidence Link**: \`${p[7].data.evidence_ref}\``,
-    `- **Overall E-E-A-T Score**: **${p[7].data.overall_eeat_score} / 5.0**`,
-    `  - Experience: ${p[7].data.experience_score} / 5.0`,
-    `  - Expertise: ${p[7].data.expertise_score} / 5.0`,
-    `  - Authoritativeness: ${p[7].data.authoritativeness_score} / 5.0`,
-    `  - Trustworthiness: ${p[7].data.trustworthiness_score} / 5.0`,
+    `- **Overall E-E-A-T Score**: **${formatVal(p[7].data.overall_eeat_score)} / 5.0**`,
+    `  - Experience: ${formatVal(p[7].data.experience_score)} / 5.0`,
+    `  - Expertise: ${formatVal(p[7].data.expertise_score)} / 5.0`,
+    `  - Authoritativeness: ${formatVal(p[7].data.authoritativeness_score)} / 5.0`,
+    `  - Trustworthiness: ${formatVal(p[7].data.trustworthiness_score)} / 5.0`,
     ``,
     `## 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**: ${p[8].data.wikidata_corroboration.toUpperCase()}`,
+    `- **External Corroboration**: ${formatVal(p[8].data.wikidata_corroboration).toUpperCase()}`,
     ``,
     `## 9. Structured-Data & Schema Architecture`,
     `- **Evidence Link**: \`${p[9].data.evidence_ref}\``,
-    `- **Deployed Schemas**: ${p[9].data.deployed_types.join(', ')}`,
-    `- **Recommended Missing Schemas**: ${p[9].data.coverage_gaps.join(', ')}`,
+    `- **Deployed Schemas**: ${(p[9].data.deployed_types || []).join(', ') || 'None'}`,
+    `- **Recommended Missing Schemas**: ${(p[9].data.coverage_gaps || []).join(', ') || 'None'}`,
     ``,
     `## 10. Competitive Search Intelligence & Share of Voice`,
     `- **Evidence Link**: \`${p[10].data.evidence_ref}\``,
-    `- **1st-Party Citation Share**: **${p[10].data.first_party_citation_share_pct}%** vs Competitors (${p[10].data.top_competitor_share_pct}%)`,
-    `- **Primary Gap**: ${p[10].data.primary_authority_gap}`,
+    `- **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)}`,
     ``,
     `## 11. Backlink & Off-Page Authority Profile`,
     `- **Evidence Link**: \`${p[11].data.evidence_ref}\``,
-    `- **Referring Domains**: ${p[11].data.referring_domains} (Authority Score: ${p[11].data.authority_score}/100)`,
-    `- **Toxic Domains**: ${p[11].data.toxic_domain_count} flagged (\`${p[11].data.disavow_recommendation}\`)`,
+    `- **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)}\`)`,
     ``,
     `## 12. Search Demand & Addressable Market Opportunity`,
-    `| Query Cluster | Addressable Volume | Commercial Intent | Current Posture |`,
-    `| :--- | :--- | :--- | :--- |`,
-    ...p[12].data.map((c) => `| ${c.cluster} | ${c.addressable_monthly_searches.toLocaleString()} | ${c.commercial_intent.toUpperCase()} | ${c.current_coverage} |`),
+  ];
+
+  const demandClusters = Array.isArray(p[12].data) ? p[12].data : (p[12].data?.clusters || []);
+  if (demandClusters.length > 0) {
+    lines.push(
+      `| Query Cluster | Addressable Volume | Commercial Intent | Current Posture |`,
+      `| :--- | :--- | :--- | :--- |`,
+      ...demandClusters.map((c) => `| ${escapeMarkdownTableCell(c.cluster)} | ${(c.addressable_monthly_searches || 0).toLocaleString()} | ${escapeMarkdownTableCell(c.commercial_intent || '').toUpperCase()} | ${escapeMarkdownTableCell(c.current_coverage || '')} |`)
+    );
+  } else {
+    lines.push(`- *Search demand telemetry not observed. External query volume integration required.*`);
+  }
+
+  lines.push(
     ``,
     `## 13. Search-to-Conversion Impact`,
-    `- **Organic Conversion Rate**: ${p[13].data.organic_conversion_rate_pct}%`,
-    `- **Attributed Pipeline MRR**: **${p[13].data.pipeline_attributed_mrr}**`,
-    `- **Assisted Conversions Share**: ${p[13].data.assisted_conversions_share_pct}%`,
+    `- **Organic Conversion Rate**: ${formatVal(p[13].data.organic_conversion_rate_pct, '%')}`,
+    `- **Attributed Pipeline MRR**: **${formatVal(p[13].data.pipeline_attributed_mrr)}**`,
+    `- **Assisted Conversions Share**: ${formatVal(p[13].data.assisted_conversions_share_pct, '%')}`,
     ``,
     `## 14. Measurement Integrity & Analytics Instrumentation`,
-    `- **GA4 & GSC**: ${p[14].data.ga4_instrumentation.toUpperCase()}`,
-    `- **Consent Mode Data Loss**: ~${p[14].data.consent_mode_v2_loss_pct}%`,
-    `- **Limitations**: ${p[14].data.known_limitations.join('; ')}`,
+    `- **GA4 & GSC**: ${formatVal(p[14].data.ga4_instrumentation).toUpperCase()} / ${formatVal(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)`,
     `| Evidence ID | Source | Methodology | Confidence | Observation Date |`,
     `| :--- | :--- | :--- | :--- | :--- |`,
-    ...report.evidence_register.map((e) => `| **${e.evidence_id}** | \`${e.source}\` | ${e.methodology.slice(0, 50)}... | \`${e.confidence_level}\` | ${e.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} |`),
     ``,
     `## 16. Strategic Risk & Algorithmic Dependency Register`,
     `| Risk ID | Category | Severity | Description | Mitigation |`,
     `| :--- | :--- | :--- | :--- | :--- |`,
-    ...p[16].data.map((r) => `| **${r.risk_id}** | \`${r.category}\` | **${r.severity.toUpperCase()}** | ${r.description} | ${r.mitigation} |`),
+    ...(p[16].data || []).map((r) => `| **${r.risk_id}** | \`${r.category}\` | **${r.severity.toUpperCase()}** | ${escapeMarkdownTableCell(r.description)} | ${escapeMarkdownTableCell(r.mitigation)} |`),
     ``,
     `## 17. ICE-BV Prioritization Matrix`,
     `- **Quick Wins Available**: ${p[17].data.summary?.quick_wins_count || 0}`,
@@ -561,9 +802,9 @@ export function renderSearchReportMarkdown(report) {
     `- **Total Prioritized Initiatives**: ${p[17].data.total_scored || 0}`,
     ``,
     `## 18. 30 / 90 / 180-Day Strategic Execution Roadmap`,
-    ...p[18].data.horizons.map((h) => `### ${h.label}\n- **Objective**: ${h.objective}\n- **Focus Areas**: ${(h.focus_areas || []).join('; ')}\n- **Exit Criteria**: ${(h.exit_criteria || []).join('; ')}`),
-    ``,
-  ];
+    ...(p[18].data.horizons || []).map((h) => `### ${sanitizeForMarkdown(h.label)}\n- **Objective**: ${sanitizeForMarkdown(h.objective)}\n- **Focus Areas**: ${(h.focus_areas || []).map((f) => sanitizeForMarkdown(f)).join('; ')}\n- **Exit Criteria**: ${(h.exit_criteria || []).map((e) => sanitizeForMarkdown(e)).join('; ')}`),
+    ``
+  );
 
   return lines.join('\n');
 }
@@ -577,7 +818,7 @@ export function renderSearchReportHtml(report) {
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <title>${report.report_title} - ${report.client_name}</title>
+  <title>${report.report_title} - ${escapeHtml(report.client_name)}</title>
   <style>
     :root { --bg: #0b0f19; --card: #151d30; --border: #1e293b; --text: #f8fafc; --muted: #94a3b8; --accent: #38bdf8; --danger: #ef4444; --warning: #f59e0b; --success: #10b981; }
     body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; margin: 0; padding: 40px 20px; }
@@ -604,51 +845,58 @@ export function renderSearchReportHtml(report) {
   <div class="container">
     <header>
       <h1>${report.report_title}</h1>
-      <div class="meta">Client: <strong>${report.client_name}</strong> | Target: <strong>${report.target_domain}</strong> | Generated: ${report.generated_at.split('T')[0]}</div>
+      <div class="meta">
+        Client: <strong>${escapeHtml(report.client_name)}</strong> &bull;
+        Target: <strong>${escapeHtml(report.target_domain)}</strong> &bull;
+        Generated: <strong>${escapeHtml(report.generated_at)}</strong> &bull;
+        Mode: <strong>${escapeHtml(report.generation_provenance.generation_mode)}</strong>
+      </div>
     </header>
 
     <div class="disclosure">
-      <strong>Enterprise Governance Premise:</strong> This executive briefing provides observable technical discovery infrastructure, AEO extraction posture, and controlled citation measurements. Every conclusion is bound to an underlying record in the Evidence Register. No search engine ranking, AI citation, or conversion outcome is guaranteed.
+      <strong>Enterprise Operating Premise:</strong> This briefing is strictly bounded by deterministic DOM analysis, observable Core Web Vitals lab heuristics, and empirical citation observation probes. No rankings or conversions are promised or implied.
     </div>
 
     <div class="grid">
-      <div class="card"><div>Overall Search & AEO Readiness</div><div class="card-num">${report.overall_readiness_score}/100</div></div>
-      <div class="card"><div>E-E-A-T Score</div><div class="card-num">${p[7].data.overall_eeat_score}/5.0</div></div>
-      <div class="card"><div>AI Overview Inclusion</div><div class="card-num">${p[1].data.google_ai_overviews.inclusion_rate_pct}%</div></div>
-      <div class="card"><div>1st-Party Citation Share</div><div class="card-num">${p[10].data.first_party_citation_share_pct}%</div></div>
-    </div>
-
-    <h2 class="section-title">Executive Decision Summary (Separated Epistemology)</h2>
-    <div class="card">
-      <h3 style="color:var(--success); margin-top:0;">Confirmed Findings (Deterministic Observations)</h3>
-      <ul>${report.decision_summary.confirmed_findings.map((f) => `<li>${f}</li>`).join('')}</ul>
-
-      <h3 style="color:var(--accent);">Inferred Opportunities (Modeled Projections)</h3>
-      <ul>${report.decision_summary.inferred_opportunities.map((o) => `<li>${o}</li>`).join('')}</ul>
-
-      <h3 style="color:var(--warning);">Unresolved Unknowns (Measurement Gaps)</h3>
-      <ul>${report.decision_summary.unresolved_unknowns.map((u) => `<li>${u}</li>`).join('')}</ul>
-
-      <h3 style="color:var(--danger);">Strategic Risks & Platform Dependencies</h3>
-      <ul>${report.decision_summary.strategic_risks.map((r) => `<li>${r}</li>`).join('')}</ul>
-
-      <h3 style="color:#c084fc;">Actions Requiring Leadership Approval</h3>
-      <ul>${report.decision_summary.actions_requiring_leadership_approval.map((a) => `<li>${a}</li>`).join('')}</ul>
+      <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>
+      </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>
+      </div>
+      <div class="card">
+        <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">E-E-A-T Quality Score</div>
+        <div class="card-num">${formatVal(p[7].data.overall_eeat_score)} / 5.0</div>
+        <span class="badge badge-success">Evaluated</span>
+      </div>
+      <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>
+      </div>
     </div>
 
-    <h2 class="section-title">Evidence Register Traceability Engine</h2>
+    <h2 class="section-title">Verified Evidence Register (${report.evidence_register.length} Observations)</h2>
     <table>
       <thead>
-        <tr><th>Evidence ID</th><th>Source Channel</th><th>Observation Date</th><th>Methodology</th><th>Confidence Level</th></tr>
+        <tr>
+          <th>Evidence ID</th>
+          <th>Source Domain / Trace</th>
+          <th>Methodology</th>
+          <th>Confidence</th>
+        </tr>
       </thead>
       <tbody>
         ${report.evidence_register.map((e) => `
           <tr>
-            <td><span class="evidence-ref">${e.evidence_id}</span></td>
-            <td><code>${e.source}</code></td>
-            <td>${e.observation_date}</td>
-            <td>${e.methodology}</td>
-            <td><span class="badge ${e.confidence_level === 'deterministic' ? 'badge-success' : 'badge-warning'}">${e.confidence_level}</span></td>
+            <td><span class="evidence-ref">${escapeHtml(e.evidence_id)}</span></td>
+            <td><code>${escapeHtml(e.source)}</code></td>
+            <td>${escapeHtml(e.methodology)}</td>
+            <td><span class="badge ${e.confidence_level === 'deterministic' ? 'badge-success' : 'badge-warning'}">${escapeHtml(e.confidence_level)}</span></td>
           </tr>
         `).join('')}
       </tbody>
@@ -656,11 +904,11 @@ export function renderSearchReportHtml(report) {
 
     <h2 class="section-title">30 / 90 / 180-Day Execution Roadmap</h2>
     <div class="grid">
-      ${p[18].data.horizons.map((h) => `
+      ${(p[18].data.horizons || []).map((h) => `
         <div class="card">
-          <div class="badge badge-success">${h.horizon.toUpperCase()}</div>
-          <h4 style="margin:8px 0;">${h.label}</h4>
-          <div style="font-size:12px; font-weight:bold; color:var(--accent);">Target Exit Criteria: ${h.exit_criteria?.[0] || 'Operational Reliability'}</div>
+          <div class="badge badge-success">${escapeHtml((h.horizon || '').toUpperCase())}</div>
+          <h4 style="margin:8px 0;">${escapeHtml(h.label)}</h4>
+          <div style="font-size:12px; font-weight:bold; color:var(--accent);">Target Exit Criteria: ${escapeHtml(h.exit_criteria?.[0] || 'Operational Reliability')}</div>
         </div>
       `).join('')}
     </div>