@nebulacomponents/citable 1.19.0 → 1.21.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/representation/prompts.js

@@ -0,0 +1,117 @@
+import { canonicalEvidenceJson } from '../evidence/hashes.js';
+import { sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const PROMPT_SCHEMA = 'prompt-set.schema.json';
+
+function without(value, key) {
+  const copy = { ...value };
+  delete copy[key];
+  return copy;
+}
+
+function promptId({ prompt_text, context = null, locale = null }) {
+  return `PROMPT-${sha256(canonicalEvidenceJson({ prompt_text, context, locale })).slice(0, 24)}`;
+}
+
+export function createPrompt(input) {
+  if (!input || typeof input.prompt_text !== 'string' || !input.prompt_text.trim()) throw new TypeError('prompt_text is required');
+  const prompt = {
+    prompt_id: input.prompt_id || promptId(input),
+    prompt_text: input.prompt_text,
+    ...(input.context == null ? {} : { context: input.context }),
+    ...(input.locale == null ? {} : { locale: input.locale }),
+  };
+  return prompt;
+}
+
+function normalizeIncluded(prompts = []) {
+  if (!Array.isArray(prompts)) throw new TypeError('included_prompts must be an array');
+  const normalized = prompts.map(createPrompt);
+  const ids = new Set();
+  for (const item of normalized) {
+    if (ids.has(item.prompt_id)) throw new Error(`duplicate prompt_id: ${item.prompt_id}`);
+    ids.add(item.prompt_id);
+  }
+  return normalized.sort((left, right) => left.prompt_id.localeCompare(right.prompt_id));
+}
+
+function normalizeExcluded(prompts = []) {
+  if (!Array.isArray(prompts)) throw new TypeError('excluded_prompts must be an array');
+  return prompts.map((item) => ({
+    prompt_id: item.prompt_id || promptId(item),
+    ...(item.prompt_text == null ? {} : { prompt_text: item.prompt_text }),
+    exclusion_reason: item.exclusion_reason,
+  })).sort((left, right) => left.prompt_id.localeCompare(right.prompt_id));
+}
+
+function hashPromptSet(item) {
+  const value = without(item, 'prompt_set_hash');
+  return sha256(canonicalEvidenceJson({
+    ...value,
+    included_prompts: [...(value.included_prompts || [])].sort((left, right) => left.prompt_id.localeCompare(right.prompt_id)),
+    excluded_prompts: [...(value.excluded_prompts || [])].sort((left, right) => left.prompt_id.localeCompare(right.prompt_id)),
+  }));
+}
+
+export function createPromptSet(input, { previous = null } = {}) {
+  if (!input || typeof input.prompt_set_id !== 'string' || !input.prompt_set_id) throw new TypeError('prompt_set_id is required');
+  if (!Number.isInteger(input.prompt_set_version) || input.prompt_set_version < 1) throw new TypeError('prompt_set_version must be a positive integer');
+  const included = normalizeIncluded(input.included_prompts);
+  const excluded = normalizeExcluded(input.excluded_prompts || []);
+  const item = {
+    prompt_set_id: input.prompt_set_id,
+    prompt_set_version: input.prompt_set_version,
+    purpose: input.purpose,
+    generation_method: input.generation_method,
+    generation_method_version: input.generation_method_version ?? null,
+    generation_input: input.generation_input ?? null,
+    generated_at: input.generated_at,
+    population_size: included.length,
+    sampling_method: input.sampling_method,
+    included_prompts: included,
+    excluded_prompts: excluded,
+    intended_population: input.intended_population,
+    limitations: [...new Set(input.limitations || [])],
+  };
+  item.prompt_set_hash = hashPromptSet(item);
+  const check = validateAgainst(PROMPT_SCHEMA, item);
+  if (!check.valid) throw new TypeError(`prompt set violates contract: ${check.errors.join('; ')}`);
+  if (previous && previous.prompt_set_id === item.prompt_set_id && previous.prompt_set_version === item.prompt_set_version && previous.prompt_set_hash !== item.prompt_set_hash) {
+    throw new Error('prompt set version is immutable; create a new prompt_set_version');
+  }
+  return item;
+}
+
+export function verifyPromptSet(item, { previous = null } = {}) {
+  const failures = [];
+  const check = validateAgainst(PROMPT_SCHEMA, item);
+  if (!check.valid) failures.push(...check.errors);
+  if (item?.prompt_set_hash !== hashPromptSet(item || {})) failures.push('prompt set hash is inconsistent');
+  if (previous && previous.prompt_set_id === item?.prompt_set_id && previous.prompt_set_version === item?.prompt_set_version && previous.prompt_set_hash !== item?.prompt_set_hash) failures.push('prompt set version is immutable');
+  return { valid: failures.length === 0, failures };
+}
+
+export function promptReference(promptSet, promptIdValue) {
+  if (!verifyPromptSet(promptSet).valid) throw new Error('cannot reference an unverifiable prompt set');
+  const prompt = promptSet.included_prompts.find((item) => item.prompt_id === promptIdValue);
+  if (!prompt) throw new Error(`prompt ${promptIdValue} is not included in prompt set ${promptSet.prompt_set_id}@${promptSet.prompt_set_version}`);
+  return `${promptSet.prompt_set_id}@${promptSet.prompt_set_version}:${prompt.prompt_id}`;
+}
+
+export function comparePromptSets(left, right) {
+  const validLeft = verifyPromptSet(left).valid;
+  const validRight = verifyPromptSet(right).valid;
+  if (!validLeft || !validRight) return { status: 'INDETERMINATE', dimensions: {}, limitations: ['Prompt-set integrity could not be verified.'] };
+  const dimensions = {
+    prompt_set_id: left.prompt_set_id === right.prompt_set_id ? 'match' : 'mismatch',
+    prompt_set_version: left.prompt_set_version === right.prompt_set_version ? 'match' : 'mismatch',
+    population: left.population_size === right.population_size ? 'match' : 'mismatch',
+    sampling_method: left.sampling_method === right.sampling_method ? 'match' : 'mismatch',
+  };
+  const status = dimensions.prompt_set_id === 'match' && dimensions.prompt_set_version === 'match' && dimensions.population === 'match' && dimensions.sampling_method === 'match'
+    ? 'COMPARABLE' : 'NOT_COMPARABLE';
+  return { status, left_reference: `${left.prompt_set_id}@${left.prompt_set_version}`, right_reference: `${right.prompt_set_id}@${right.prompt_set_version}`, dimensions, limitations: status === 'COMPARABLE' ? [] : ['Prompt population, sampling, or version changed; no denominator is reused silently.'] };
+}
+
+export { promptId };

package/src/representation/representation.js

@@ -0,0 +1,186 @@
+import { createExternalObservation, verifyExternalObservation } from '../evidence/external.js';
+import { canonicalEvidenceJson } from '../evidence/hashes.js';
+import { sha256, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import { verifyPromptSet, promptReference } from './prompts.js';
+
+const REPRESENTATION_SCHEMA = 'representation-data.schema.json';
+const COLLECTOR = { id: 'citable-representation-observations', version: '1.0.0' };
+const PARSER = { id: 'provider-neutral-representation-parser', version: '1.0.0' };
+
+function responseHash(rawResponse, response) {
+  return sha256(typeof rawResponse === 'string' ? rawResponse : canonicalEvidenceJson(response ?? null));
+}
+
+function modelIdentity(model) {
+  if (model && typeof model === 'string') return { value: model, status: 'known' };
+  if (model && typeof model === 'object' && ['known', 'UNKNOWN', 'UNAVAILABLE', 'NOT_DISCLOSED'].includes(model.status)) return { value: model.value ?? null, status: model.status };
+  return { value: null, status: 'UNKNOWN' };
+}
+
+function hostOf(value) {
+  try { return new URL(value).hostname.toLowerCase(); } catch { return null; }
+}
+
+function normalizeUrls(value) {
+  if (!Array.isArray(value)) throw new TypeError('provider citations must be an array');
+  const urls = value.map((item) => typeof item === 'string' ? item : item?.url);
+  if (urls.some((item) => typeof item !== 'string' || !hostOf(item))) throw new TypeError('provider citation URL is malformed');
+  return [...new Set(urls)];
+}
+
+const SENSITIVE_KEY = /(^|[-_])(authorization|cookie|set-cookie|access[-_]?token|refresh[-_]?token|api[-_]?key|password|secret)($|[-_])/i;
+
+function safeMetadata(value, depth = 0) {
+  if (depth > 4 || value == null) return value == null ? null : '[bounded]';
+  if (Array.isArray(value)) return value.slice(0, 50).map((item) => safeMetadata(item, depth + 1));
+  if (typeof value !== 'object') return typeof value === 'string' ? value.slice(0, 500) : value;
+  return Object.fromEntries(Object.entries(value).slice(0, 50).filter(([key]) => !SENSITIVE_KEY.test(key)).map(([key, item]) => [key, safeMetadata(item, depth + 1)]));
+}
+
+function executionStatusFor(status) {
+  if (status === 'succeeded') return { observation_status: 'observed', retrieval_status: 'retrieved' };
+  if (status === 'malformed' || status === 'parser_failed') return { observation_status: 'indeterminate', retrieval_status: 'indeterminate' };
+  return { observation_status: 'failed', retrieval_status: 'failed' };
+}
+
+function parserErrorObservation({ provider, product, surface, prompt, promptSet, executionConfiguration, model, evidenceOrigin, executedAt, rawResponse, status, errorMessage }) {
+  const hash = responseHash(rawResponse, null);
+  const execution = executionConfiguration || { id: 'default', version: '1.0.0' };
+  const state = executionStatusFor(status);
+  return createRepresentationObservation({
+    provider, product, surface, prompt, promptSet, executionConfiguration: execution, model, evidenceOrigin, executedAt,
+    response: { status, response_hash: hash, parser: PARSER, raw_response_retained: false, provider_metadata: {} },
+    representation: { brand_mentioned: null, domain_mentioned: null, domain_cited: null, cited_urls: [], mentioned_entities: [], cited_domains: [] },
+    observationStatus: state.observation_status, retrievalStatus: state.retrieval_status,
+    limitations: [`Representation response could not be normalized: ${String(errorMessage || status).slice(0, 240)}`, 'Raw provider response is not retained; response_hash is retained for identity.'],
+  });
+}
+
+export function createRepresentationObservation({ provider, product, surface, prompt, promptSet, executionConfiguration, model, evidenceOrigin, executedAt = nowIso(), response, representation, observationStatus = 'observed', retrievalStatus = 'retrieved', limitations = [] }) {
+  if (!provider || !product || !surface) throw new TypeError('provider, product, and surface are required');
+  if (!prompt || !prompt.prompt_id || !prompt.prompt_text) throw new TypeError('prompt identity and text are required');
+  if (!promptSet || !verifyPromptSet(promptSet).valid) throw new TypeError('prompt set is missing or unverifiable');
+  if (!promptSet.included_prompts.some((item) => item.prompt_id === prompt.prompt_id)) throw new Error(`prompt ${prompt.prompt_id} is not included in the prompt set`);
+  if (!['LIVE_PROVIDER', 'RECORDED_FIXTURE', 'SYNTHETIC_TEST'].includes(evidenceOrigin)) throw new TypeError('evidenceOrigin is invalid');
+  const config = executionConfiguration || { id: 'default', version: '1.0.0' };
+  const normalizedModel = modelIdentity(model);
+  const data = {
+    provider,
+    product,
+    surface,
+    model: normalizedModel,
+    prompt: { prompt_id: prompt.prompt_id, prompt_version: promptSet.prompt_set_version, prompt_text: prompt.prompt_text },
+    prompt_set: { prompt_set_id: promptSet.prompt_set_id, prompt_set_version: promptSet.prompt_set_version },
+    execution: { executed_at: executedAt, configuration: config },
+    response,
+    representation,
+    evidence_origin: evidenceOrigin,
+    limitations: [...new Set(limitations)],
+  };
+  const check = validateAgainst(REPRESENTATION_SCHEMA, data);
+  if (!check.valid) throw new TypeError(`representation data violates contract: ${check.errors.join('; ')}`);
+  const state = executionStatusFor(response.status);
+  const observation = createExternalObservation({
+    observation_id: `REP-${sha256(canonicalEvidenceJson({ provider, product, surface, prompt, promptSet: promptSet.prompt_set_hash, executedAt, response })).slice(0, 24)}`,
+    observation_type: 'EXTERNAL_OBSERVATION',
+    subject: { type: 'prompt_execution', id: promptReference(promptSet, prompt.prompt_id) },
+    source: { provider, method: 'representation_adapter', authority: 'external_provider' },
+    collector: COLLECTOR,
+    parser: PARSER,
+    configuration: config,
+    observed_at: executedAt,
+    retrieved_at: executedAt,
+    executed_at: executedAt,
+    population: { declared: { id: `${promptSet.prompt_set_id}@${promptSet.prompt_set_version}`, size: promptSet.population_size }, observed: 1, retrieved: response.status === 'succeeded' ? 1 : 0, evaluated: response.status === 'succeeded' ? 1 : 0, unavailable: response.status === 'unavailable' ? 1 : 0, failed: response.status === 'succeeded' ? 0 : 1 },
+    observation_status: observationStatus || state.observation_status,
+    retrieval_status: retrievalStatus || state.retrieval_status,
+    data,
+    lineage: { source_evidence: response.response_hash ? [response.response_hash] : [] },
+    limitations: data.limitations,
+  });
+  return observation;
+}
+
+export function normalizeRepresentationResponse({ provider, product, surface, prompt, promptSet, executionConfiguration, model, response, rawResponse = null, evidenceOrigin = 'RECORDED_FIXTURE', executedAt = nowIso(), brand = null, firstPartyDomains = [], retainRawResponse = false }) {
+  const base = { provider, product, surface, prompt, promptSet, executionConfiguration, model, evidenceOrigin, executedAt };
+  const rawHash = responseHash(rawResponse, response);
+  try {
+    if (!response || typeof response !== 'object' || Array.isArray(response)) throw new TypeError('provider response must be an object');
+    const answerText = response.answer_text ?? response.answer ?? response.text;
+    if (typeof answerText !== 'string') throw new TypeError('provider response requires answer_text');
+    const citations = normalizeUrls(response.citations || []);
+    const mentionedEntities = Array.isArray(response.mentions) ? response.mentions.filter((item) => typeof item === 'string') : [];
+    const firstParty = new Set(firstPartyDomains.map((item) => String(item).toLowerCase()));
+    const citedDomains = [...new Set(citations.map(hostOf).filter(Boolean))];
+    const domainMentioned = firstParty.size ? [...firstParty].some((domain) => answerText.toLowerCase().includes(domain)) : null;
+    const domainCited = firstParty.size ? citedDomains.some((domain) => firstParty.has(domain)) : null;
+    const brandMentioned = typeof brand === 'string' ? answerText.toLowerCase().includes(brand.toLowerCase()) : null;
+    return createRepresentationObservation({
+      ...base,
+      response: { status: 'succeeded', response_hash: rawHash, parser: PARSER, raw_response_retained: retainRawResponse, provider_metadata: { ...safeMetadata(response.provider_metadata || {}), ...(retainRawResponse ? { raw_response: rawResponse ?? response } : {}) } },
+      representation: { brand_mentioned: brandMentioned, domain_mentioned: domainMentioned, domain_cited: domainCited, cited_urls: citations, mentioned_entities: mentionedEntities, cited_domains: citedDomains },
+      limitations: retainRawResponse ? [] : ['Raw provider response is not retained; response_hash is retained for identity.'],
+    });
+  } catch (error) {
+    return parserErrorObservation({ ...base, rawResponse, status: 'parser_failed', errorMessage: error.message });
+  }
+}
+
+export async function collectRepresentationObservations({ promptSet, adapter, provider, product = 'unknown', surface = 'unknown', model = null, executionConfiguration = { id: 'default', version: '1.0.0' }, evidenceOrigin = 'LIVE_PROVIDER', brand = null, firstPartyDomains = [] } = {}) {
+  if (!promptSet || !verifyPromptSet(promptSet).valid) throw new TypeError('prompt set is missing or unverifiable');
+  if (typeof adapter !== 'function') throw new TypeError('representation adapter is required');
+  const observations = [];
+  for (const prompt of promptSet.included_prompts) {
+    const executedAt = nowIso();
+    try {
+      const result = await adapter(prompt, { provider, product, surface, model, promptSet, executionConfiguration });
+      if (!result || typeof result !== 'object') throw new Error('adapter returned an invalid result');
+      const status = result.status || 'succeeded';
+      if (status !== 'succeeded') {
+        observations.push(parserErrorObservation({ provider, product, surface, prompt, promptSet, executionConfiguration, model, evidenceOrigin, executedAt, rawResponse: result.raw ?? result.body ?? null, status, errorMessage: result.error || status }));
+      } else {
+        observations.push(normalizeRepresentationResponse({ provider, product, surface, prompt, promptSet, executionConfiguration, model, response: result.body ?? result.response ?? result, rawResponse: result.raw ?? null, evidenceOrigin, executedAt, brand, firstPartyDomains }));
+      }
+    } catch (error) {
+      observations.push(parserErrorObservation({ provider, product, surface, prompt, promptSet, executionConfiguration, model, evidenceOrigin, executedAt, rawResponse: null, status: error.connectorState === 'quota_limited' ? 'rate_limited' : error.name === 'AbortError' ? 'timeout' : 'error', errorMessage: error.message }));
+    }
+  }
+  return { observations, coverage: { declared: promptSet.population_size, executed: observations.filter((item) => item.data.response.status === 'succeeded').length, failed: observations.filter((item) => item.data.response.status !== 'succeeded').length, coverage_status: observations.every((item) => item.data.response.status === 'succeeded') ? 'complete_for_declared_prompt_set' : 'incomplete' }, prompt_set_reference: `${promptSet.prompt_set_id}@${promptSet.prompt_set_version}` };
+}
+
+export function createHttpRepresentationAdapter({ endpoint, fetchImpl = globalThis.fetch, accessToken = null } = {}) {
+  if (typeof endpoint !== 'string' || !/^https:\/\//.test(endpoint)) throw new TypeError('representation adapter endpoint must use HTTPS');
+  return async (prompt) => {
+    const response = await fetchImpl(endpoint, { method: 'POST', redirect: 'error', headers: { accept: 'application/json', 'content-type': 'application/json', ...(accessToken ? { authorization: `Bearer ${accessToken}` } : {}) }, body: JSON.stringify({ prompt_id: prompt.prompt_id, prompt_text: prompt.prompt_text }) });
+    const raw = await response.text();
+    if (!response.ok) {
+      const status = response.status === 429 ? 'rate_limited' : response.status === 408 ? 'timeout' : response.status >= 500 ? 'unavailable' : 'refused';
+      return { status, raw, error: `provider returned ${response.status}` };
+    }
+    let body;
+    try { body = JSON.parse(raw); } catch { return { status: 'malformed', raw, error: 'provider response was not valid JSON' }; }
+    return { status: 'succeeded', body, raw };
+  };
+}
+
+export function verifyRepresentationObservation(item) {
+  return verifyExternalObservation(item);
+}
+
+export function compareRepresentationObservations(left, right) {
+  if (!verifyExternalObservation(left).valid || !verifyExternalObservation(right).valid) return { status: 'INDETERMINATE', dimensions: {}, limitations: ['Representation observation integrity could not be verified.'] };
+  const dimensions = {
+    provider: left.data.provider === right.data.provider ? 'match' : 'mismatch',
+    product: left.data.product === right.data.product ? 'match' : 'mismatch',
+    surface: left.data.surface === right.data.surface ? 'match' : 'mismatch',
+    model: left.data.model.status !== 'known' || right.data.model.status !== 'known' ? 'missing' : left.data.model.value === right.data.model.value ? 'match' : 'mismatch',
+    prompt: left.data.prompt.prompt_id === right.data.prompt.prompt_id && left.data.prompt.prompt_text === right.data.prompt.prompt_text ? 'match' : 'mismatch',
+    prompt_set: left.data.prompt_set.prompt_set_id === right.data.prompt_set.prompt_set_id && left.data.prompt_set.prompt_set_version === right.data.prompt_set.prompt_set_version ? 'match' : 'mismatch',
+    configuration: left.data.execution.configuration.id === right.data.execution.configuration.id && left.data.execution.configuration.version === right.data.execution.configuration.version ? 'match' : 'mismatch',
+    parser: left.data.response.parser.id === right.data.response.parser.id && left.data.response.parser.version === right.data.response.parser.version ? 'match' : 'mismatch',
+  };
+  const hardMismatch = ['provider', 'product', 'surface', 'prompt', 'prompt_set', 'configuration', 'parser'].some((key) => dimensions[key] === 'mismatch');
+  const status = hardMismatch ? 'NOT_COMPARABLE' : dimensions.model === 'mismatch' ? 'NOT_COMPARABLE' : dimensions.model === 'missing' ? 'PARTIALLY_COMPARABLE' : 'COMPARABLE';
+  return { comparison_id: `REP-CMP-${sha256(canonicalEvidenceJson({ left: left.observation_id, right: right.observation_id, dimensions })).slice(0, 16)}`, left_reference: left.observation_id, right_reference: right.observation_id, status, dimensions, limitations: status === 'COMPARABLE' ? [] : ['Provider, model, prompt, execution, and parser identity remain explicit; no visibility delta is inferred from non-comparable observations.'] };
+}