@nebulacomponents/citable 1.13.1 → 1.15.0

package/src/installer/providers.js

@@ -7,8 +7,10 @@ export const PROVIDERS = Object.freeze({
     aliases: ['claude-code', 'claudecode'],
     projectDir: '.claude',
     projectSkillsDir: '.claude/skills',
+    projectAgentProfilesDir: '.claude/agents',
     globalHints: ['.claude'],
     globalSkillsDir: '.claude/skills',
+    globalAgentProfilesDir: '.claude/agents',
   },
   codex: {
     id: 'codex',
@@ -162,3 +164,12 @@ export function providerBundleSkillPath(providerId) {
   if (!provider) throw new Error(`unknown provider: ${providerId}`);
   return path.join('dist', 'universal', provider.projectSkillsDir, 'citable');
 }
+
+export function providerAgentProfilesDestination(providerId, scope, roots) {
+  const provider = PROVIDERS[providerId];
+  if (!provider) throw new Error(`unknown provider: ${providerId}`);
+  const dir = scope === 'project' ? provider.projectAgentProfilesDir : provider.globalAgentProfilesDir;
+  if (!dir) return null;
+  const root = scope === 'project' ? roots.projectRoot : roots.home;
+  return path.join(root, dir, 'citable');
+}

package/src/monitoring/alertDelivery.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { validatePublicUrl } from '../crawler/fetch.js';
+import { nowIso, sha256, writeJson } from '../shared/io.js';
+
+export const SEVERITY_ORDER = {
+  informational: 1,
+  medium: 2,
+  high: 3,
+  critical: 4,
+};
+
+export function filterAlerts(alerts = [], minSeverity = 'informational') {
+  const minRank = SEVERITY_ORDER[minSeverity] ?? SEVERITY_ORDER.informational;
+  return alerts.filter((item) => (SEVERITY_ORDER[item.severity] ?? 0) >= minRank);
+}
+
+export function buildAlertPayload({ runA, runB, source = 'monitor', summary = {}, alerts = [], timestamp = nowIso() } = {}) {
+  const critOrHigh = alerts.filter((a) => ['critical', 'high'].includes(a.severity)).length;
+  return {
+    event: 'citable.regression_alert',
+    source,
+    generated_at: timestamp,
+    run_a: runA ?? null,
+    run_b: runB,
+    summary: {
+      total_alerts: alerts.length,
+      critical_or_high: critOrHigh,
+      ...summary,
+    },
+    alerts,
+  };
+}
+
+export async function dispatchAlertWebhook(root, payload, {
+  webhookUrl,
+  headers = {},
+  timeoutMs = 10000,
+  fetchImpl = globalThis.fetch,
+  lookup,
+  allowPrivateForTest = false,
+} = {}) {
+  if (!webhookUrl) throw new Error('webhookUrl is required for alert dispatch');
+  if (!allowPrivateForTest) {
+    await validatePublicUrl(webhookUrl, { lookup });
+  }
+
+  const deliveryId = `DELIVERY-${nowIso().replace(/[:.]/g, '')}-${crypto.randomBytes(4).toString('hex')}`;
+  const payloadString = JSON.stringify(payload);
+  const payloadHash = sha256(Buffer.from(payloadString));
+  const deliveriesDir = path.join(root, '.citable', 'monitoring', 'deliveries');
+  const receiptFile = path.join(deliveriesDir, `${deliveryId}.json`);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let statusCode = null;
+  let success = false;
+  let errorMessage = null;
+
+  try {
+    const res = await fetchImpl(webhookUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-citable-event': 'citable.regression_alert',
+        'x-citable-delivery': deliveryId,
+        ...headers,
+      },
+      body: payloadString,
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    statusCode = res.status;
+    success = res.ok;
+    if (!res.ok) {
+      errorMessage = `HTTP ${res.status} ${res.statusText || 'Error'}`;
+    }
+  } catch (err) {
+    clearTimeout(timer);
+    errorMessage = err.name === 'AbortError' ? `Request timed out after ${timeoutMs}ms` : err.message;
+  }
+
+  const receipt = {
+    delivery_id: deliveryId,
+    target_url: webhookUrl,
+    delivered_at: nowIso(),
+    status_code: statusCode,
+    success,
+    payload_hash: payloadHash,
+    error: errorMessage,
+    summary: payload.summary,
+  };
+
+  writeJson(receiptFile, receipt);
+  return { ...receipt, receipt_file: receiptFile };
+}

package/src/observations/browserJourney.js

@@ -1,11 +1,15 @@
 import { envelope, observationRun, readInput } from './common.js';
-import { fetchUrl } from '../crawler/fetch.js';
+import { fetchUrl, handlePublicBrowserRoute, validatePublicUrl } from '../crawler/fetch.js';
 import { sha256 } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { analyzeRenderParity } from './renderParity.js';
 
-async function executeStep(page, step) {
+async function executeStep(page, step, lookup) {
   const locator = step.locator ? page.locator(step.locator).first() : null;
-  if (step.action === 'navigate') await page.goto(step.url, { waitUntil: 'networkidle' });
+  if (step.action === 'navigate') {
+    await validatePublicUrl(step.url, lookup ? { lookup } : {});
+    await page.goto(step.url, { waitUntil: 'networkidle' });
+  }
   else if (step.action === 'click') await locator.click();
   else if (step.action === 'fill') {
     const value = process.env[step.value_env];
@@ -22,7 +26,7 @@ async function executeStep(page, step) {
   else if (step.action === 'scroll') await locator.scrollIntoViewIfNeeded();
 }
 
-async function playwrightCapture(profile, plan, playwright) {
+async function playwrightCapture(profile, plan, playwright, lookup) {
   if (profile.authentication_state !== 'anonymous') throw new Error(`authentication state ${profile.authentication_state} requires a disclosed custom adapter`);
   const browserType = playwright[profile.browser.engine];
   if (!browserType) throw new Error(`Playwright engine ${profile.browser.engine} is unavailable`);
@@ -35,6 +39,7 @@ async function playwrightCapture(profile, plan, playwright) {
       locale: profile.locale,
     });
     try {
+      await context.route('**/*', (route) => handlePublicBrowserRoute(route, lookup ? { lookup } : {}));
       const page = await context.newPage();
       const consoleErrors = [], networkFailures = [], steps = [], stepScreenshots = {};
       page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); });
@@ -43,7 +48,7 @@ async function playwrightCapture(profile, plan, playwright) {
       for (const step of profile.steps) {
         const record = { step_id: step.step_id, action: step.action, status: 'completed', failure: null, screenshot_ref: null };
         try {
-          await executeStep(page, step);
+          await executeStep(page, step, lookup);
           if (step.capture_screenshot) {
             record.screenshot_ref = `journeys/${profile.profile_id}/steps/${step.step_id}.png`;
             stepScreenshots[record.screenshot_ref] = await page.screenshot({ fullPage: true });
@@ -79,6 +84,7 @@ export async function observeBrowserPlan(root, options) {
   const check = validateAgainst('browser-evidence-plan.schema.json', plan);
   if (!check.valid) throw new Error(`browser evidence plan violates contract: ${check.errors.join('; ')}`);
   if (options.target && options.target !== plan.target) throw new Error('browser evidence target differs from the plan target');
+  await validatePublicUrl(plan.target, options.lookup ? { lookup: options.lookup } : {});
   const profileIds = plan.profiles.map((item) => item.profile_id);
   if (new Set(profileIds).size !== profileIds.length) throw new Error('browser evidence plan contains duplicate profile ids');
   const targetOrigin = new URL(plan.target).origin;
@@ -113,7 +119,7 @@ export async function observeBrowserPlan(root, options) {
     try {
       const capture = options.captureJourney
         ? await options.captureJourney(profile, plan)
-        : await playwrightCapture(profile, plan, playwright);
+        : await playwrightCapture(profile, plan, playwright, options.lookup);
       if (!capture || typeof capture.dom !== 'string' || typeof capture.text !== 'string' || typeof capture.browser_version !== 'string' || capture.screenshot == null) {
         throw new Error('browser adapter returned an incomplete capture contract');
       }
@@ -137,6 +143,7 @@ export async function observeBrowserPlan(root, options) {
         artifacts[name] = value;
       }
       const versionMatches = profile.browser.expected_version == null || profile.browser.expected_version === capture.browser_version;
+      const renderParity = analyzeRenderParity(initial.body, capture.dom, plan.semantic_impact_policy || null);
       const data = {
         plan_id: plan.plan_id, target: plan.target, profile_id: profile.profile_id,
         browser: { ...profile.browser, observed_version: capture.browser_version, version_matches_expectation: versionMatches },
@@ -144,9 +151,10 @@ export async function observeBrowserPlan(root, options) {
         consent_state: profile.consent_state, authentication_state: profile.authentication_state,
         final_url: capture.final_url, status: capture.status, dom_hash: sha256(capture.dom), text_hash: sha256(capture.text),
         steps: capture.steps || [], artifact_refs: refs,
+        render_parity: renderParity,
         interpretation_boundary: 'Observed differences do not establish semantic, retrieval, citation, ranking, or business impact.',
       };
-      const limitations = [...plan.limitations, ...profile.limitations];
+      const limitations = [...plan.limitations, ...profile.limitations, ...(plan.semantic_impact_policy?.limitations || [])];
       if (!versionMatches) limitations.push('Observed browser version differs from the planned version.');
       observations.push(envelope('browser_journey', data, { method: 'browser', source: `playwright/${profile.browser.engine}`, raw: capture.dom, limitations }));
     } catch (error) {

package/src/observations/claimDiff.js

@@ -0,0 +1,83 @@
+import { substantiate } from '../commands/substantiate.js';
+import { loadRegistries } from '../registries/index.js';
+
+function keyTerms(text) {
+  return (String(text || '').toLowerCase().match(/[a-z][a-z-]{4,}/g) || []).slice(0, 8);
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function overlapScore(assertionText, claimText) {
+  const terms = keyTerms(assertionText);
+  if (terms.length < 3) return 0;
+  const target = String(claimText || '').toLowerCase();
+  // Whole-word boundaries only — a raw substring test would match "test" inside
+  // "greatest" and misassign a substantiation status to the wrong claim.
+  const present = terms.filter((t) => new RegExp(`\\b${escapeRegExp(t)}\\b`).test(target)).length;
+  return present / terms.length;
+}
+
+function surfaceMatches(citationUrl, surface) {
+  try {
+    const url = new URL(citationUrl);
+    // Path-boundary comparison, not raw substring — a query string or fragment
+    // containing the surface text must not count as a match.
+    return url.pathname === surface || url.pathname.startsWith(surface.endsWith('/') ? surface : `${surface}/`);
+  } catch {
+    return false;
+  }
+}
+
+/** Find the best-matching registry claim for one AI answer assertion (token-overlap heuristic, adapted from CLAIM-008). */
+export function matchClaim(assertionText, claims, citationUrl) {
+  let best = null;
+  let bestScore = 0;
+  for (const c of claims.filter((c) => c.status !== 'retired')) {
+    let score = overlapScore(assertionText, c.claim);
+    if (citationUrl && (c.publication_surfaces || []).some((s) => surfaceMatches(citationUrl, s))) score += 0.1;
+    if (score > bestScore) {
+      bestScore = score;
+      best = c;
+    }
+  }
+  return bestScore >= 0.4 ? best : null;
+}
+
+const OUTCOME_TO_STATUS = {
+  verified: 'confirmed',
+  verified_narrowed: 'confirmed',
+  contradicted: 'contradicted',
+  expired: 'stale',
+};
+
+/**
+ * Diff one answer-engine assertion against the caller's own claim/evidence registry.
+ * Never asserts the AI is wrong — only confirmed/contradicted/stale/unsupported relative
+ * to the caller's own evidence. Never implies a live query happened.
+ */
+export function diffAssertion(assertionText, citationUrl, { claims, assessmentByClaimId }) {
+  if (!assertionText) return null;
+  const matched = matchClaim(assertionText, claims, citationUrl);
+  if (!matched) {
+    return { status: 'unsupported', matched_claim_id: null, reasons: ['no claim in your registry covers this assertion; it could not be checked'] };
+  }
+  const assessment = assessmentByClaimId.get(matched.claim_id);
+  const status = OUTCOME_TO_STATUS[assessment?.outcome] ?? 'unsupported';
+  return { status, matched_claim_id: matched.claim_id, reasons: assessment?.reasons ?? [] };
+}
+
+/**
+ * Precompute the shared claim/evidence lookups once per `observe citations` run.
+ * `problems` surfaces registry schema-validation issues (malformed but parseable
+ * YAML) so the caller can report them as warnings rather than silently diffing
+ * against data that failed its own contract.
+ */
+export function buildClaimDiffContext(root, refDate) {
+  const { registries, problems } = loadRegistries(root);
+  const claims = Array.isArray(registries.claims?.entries) ? registries.claims.entries : [];
+  const { assessments } = substantiate(root, { write: false, refDate });
+  const assessmentByClaimId = new Map(assessments.map((a) => [a.claim_id, a]));
+  return { claims, assessmentByClaimId, problems };
+}

package/src/observations/common.js

@@ -42,6 +42,8 @@ export function summarizeObservations(items) {
   for (const item of items) { byKind[item.kind] = (byKind[item.kind] || 0) + 1; byState[item.state] = (byState[item.state] || 0) + 1; }
   const citations = items.filter((item) => item.kind === 'citation');
   const reviews = items.filter((item) => item.kind === 'citation_review');
+  const claimDiffCounts = { confirmed: 0, contradicted: 0, stale: 0, unsupported: 0, not_checked: 0 };
+  for (const review of reviews) claimDiffCounts[review.data.claim_diff?.status ?? 'not_checked']++;
   const providers = {};
   for (const item of citations) {
     const provider = item.data.provider || 'unknown';
@@ -49,6 +51,18 @@ export function summarizeObservations(items) {
     providers[provider].runs++;
     if (item.data.property_cited) providers[provider].property_cited++;
   }
+  const competitiveSourceMap = new Map();
+  for (const review of reviews.filter((item) => !item.data.first_party)) {
+    let domain;
+    try { domain = new URL(review.data.canonical_url).hostname; } catch { continue; }
+    const current = competitiveSourceMap.get(domain) || { domain, citation_count: 0, declared_profiles: [] };
+    current.citation_count++;
+    if (review.data.source_profile && !current.declared_profiles.some((item) => JSON.stringify(item) === JSON.stringify(review.data.source_profile))) {
+      current.declared_profiles.push(review.data.source_profile);
+    }
+    competitiveSourceMap.set(domain, current);
+  }
+  const stances = items.filter((item) => item.kind === 'stance');
   return {
     total: items.length, by_kind: byKind, by_state: byState,
     citation_metrics: citations.length ? {
@@ -56,8 +70,19 @@ export function summarizeObservations(items) {
       citation_presence_rate: citations.filter((x) => x.data.property_cited).length / citations.length,
       supported_citation_rate: reviews.length ? reviews.filter((x) => x.data.support_status === 'supported').length / reviews.length : null,
       review_required: reviews.filter((x) => x.state === 'review_required').length,
+      claim_diff: claimDiffCounts,
       provider_results: providers,
       competitive_domains: [...new Set(reviews.filter((x) => !x.data.first_party).map((x) => { try { return new URL(x.data.canonical_url).hostname; } catch { return null; } }).filter(Boolean))].sort(),
+      competitive_sources: [...competitiveSourceMap.values()].sort((a, b) => a.domain.localeCompare(b.domain)),
+    } : null,
+    stance_metrics: stances.length ? {
+      total: stances.length,
+      favorable: stances.filter((x) => x.data.stance === 'favorable').length,
+      neutral: stances.filter((x) => x.data.stance === 'neutral').length,
+      unfavorable: stances.filter((x) => x.data.stance === 'unfavorable').length,
+      mixed: stances.filter((x) => x.data.stance === 'mixed').length,
+      ambiguous: stances.filter((x) => x.data.stance === 'ambiguous').length,
+      review_required: stances.filter((x) => x.state === 'review_required').length,
     } : null,
   };
 }

package/src/observations/entityGraph.js

@@ -0,0 +1,89 @@
+import { sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const list = (value) => Array.isArray(value) ? value : value == null ? [] : [value];
+
+function visibleSupport(node, page) {
+  const candidates = [
+    ...list(node.name).map((value) => ['name', value]),
+    ...list(node.headline).map((value) => ['headline', value]),
+    ...list(node.description).map((value) => ['description', value]),
+  ].filter(([, value]) => typeof value === 'string' && value.trim());
+  if (!candidates.length) return { status: 'not_testable', matched_fields: [] };
+  const visible = `${page.title || ''} ${page.text || ''}`.toLocaleLowerCase();
+  const matchedFields = [...new Set(candidates
+    .filter(([, value]) => visible.includes(value.trim().toLocaleLowerCase()))
+    .map(([field]) => field))].sort();
+  return { status: matchedFields.length ? 'supported' : 'not_observed', matched_fields: matchedFields };
+}
+
+function referencedIds(value, relation, out = []) {
+  if (Array.isArray(value)) {
+    for (const item of value) referencedIds(item, relation, out);
+  } else if (value && typeof value === 'object') {
+    if (typeof value['@id'] === 'string') out.push({ relation, target_id: value['@id'] });
+    else for (const [key, nested] of Object.entries(value)) referencedIds(nested, key, out);
+  }
+  return out;
+}
+
+export function buildEntityGraph(pages) {
+  const nodeMap = new Map();
+  const pendingEdges = [];
+  const parseFailures = [];
+  for (const page of pages) {
+    for (const script of page.jsonLd) {
+      if (script.parseError) {
+        parseFailures.push({ url: page.url, error: script.parseError, raw_hash: sha256(script.raw) });
+        continue;
+      }
+      for (const block of script.blocks) {
+        if (!block || typeof block !== 'object' || Array.isArray(block)) continue;
+        const blockHash = sha256(JSON.stringify(block));
+        const nodeId = typeof block['@id'] === 'string' && block['@id'].trim()
+          ? block['@id']
+          : `urn:citable:jsonld:${blockHash}`;
+        const prior = nodeMap.get(nodeId) || {
+          node_id: nodeId, types: [], names: [], source_blocks: [],
+          visible_support: { status: 'not_testable', matched_fields: [] },
+        };
+        prior.types = [...new Set([...prior.types, ...list(block['@type']).filter((value) => typeof value === 'string')])].sort();
+        prior.names = [...new Set([...prior.names, ...list(block.name).filter((value) => typeof value === 'string' && value.trim())])].sort();
+        prior.source_blocks.push({ url: page.url, block_hash: blockHash });
+        const support = visibleSupport(block, page);
+        prior.visible_support = {
+          status: prior.visible_support.status === 'supported' || support.status === 'supported'
+            ? 'supported'
+            : prior.visible_support.status === 'not_observed' || support.status === 'not_observed'
+              ? 'not_observed'
+              : 'not_testable',
+          matched_fields: [...new Set([...prior.visible_support.matched_fields, ...support.matched_fields])].sort(),
+        };
+        nodeMap.set(nodeId, prior);
+        for (const [relation, value] of Object.entries(block)) {
+          if (relation.startsWith('@')) continue;
+          for (const ref of referencedIds(value, relation)) {
+            pendingEdges.push({ source_id: nodeId, relation: ref.relation, target_id: ref.target_id, source_url: page.url });
+          }
+        }
+      }
+    }
+  }
+  const nodes = [...nodeMap.values()].sort((a, b) => a.node_id.localeCompare(b.node_id));
+  const nodeIds = new Set(nodes.map((node) => node.node_id));
+  const allEdges = pendingEdges.map((edge) => ({ ...edge, target_declared: nodeIds.has(edge.target_id) }))
+    .sort((a, b) => `${a.source_id}:${a.relation}:${a.target_id}`.localeCompare(`${b.source_id}:${b.relation}:${b.target_id}`));
+  const graph = {
+    version: 1,
+    nodes,
+    edges: allEdges.filter((edge) => edge.target_declared),
+    unresolved_references: allEdges.filter((edge) => !edge.target_declared),
+    parse_failures: parseFailures,
+    limitations: [
+      'Normalization reports declared JSON-LD structure and literal visible-text matches; it does not establish semantic correctness, eligibility, search-engine recognition, or ranking impact.',
+    ],
+  };
+  const check = validateAgainst('entity-graph.schema.json', graph);
+  if (!check.valid) throw new Error(`entity graph violates contract: ${check.errors.join('; ')}`);
+  return graph;
+}

package/src/observations/renderParity.js

@@ -0,0 +1,49 @@
+import { parse } from 'node-html-parser';
+import { sha256 } from '../shared/io.js';
+
+function profile(html) {
+  const root = parse(String(html || ''));
+  for (const node of root.querySelectorAll('script,style,noscript,nav,footer,header[role=banner]')) node.remove();
+  const text = root.textContent.replace(/\s+/g, ' ').trim();
+  const tokens = new Set(text.toLocaleLowerCase().split(/\s+/).filter(Boolean));
+  const headings = root.querySelectorAll('h1,h2,h3,h4,h5,h6').map((node) => node.text.replace(/\s+/g, ' ').trim()).filter(Boolean).sort();
+  const links = root.querySelectorAll('a[href]').map((node) => node.getAttribute('href')).filter(Boolean).sort();
+  const structuredData = parse(String(html || '')).querySelectorAll('script[type="application/ld+json"]').map((node) => sha256(node.text)).sort();
+  return { text, tokens, headings, links, structuredData };
+}
+
+const missing = (before, after) => before.filter((value) => !after.includes(value));
+
+export function analyzeRenderParity(initialHtml, renderedHtml, policy = null) {
+  const initial = profile(initialHtml);
+  const rendered = profile(renderedHtml);
+  const retained = [...initial.tokens].filter((token) => rendered.tokens.has(token)).length;
+  const textRetentionRatio = initial.tokens.size ? Number((retained / initial.tokens.size).toFixed(3)) : null;
+  const removedHeadings = missing(initial.headings, rendered.headings);
+  const removedLinks = missing(initial.links, rendered.links);
+  const structuredDataMatches = JSON.stringify(initial.structuredData) === JSON.stringify(rendered.structuredData);
+  const violations = [];
+  if (policy) {
+    if (textRetentionRatio != null && textRetentionRatio < policy.min_text_retention_ratio) {
+      violations.push({ check: 'text_retention', observed: textRetentionRatio, required: policy.min_text_retention_ratio });
+    }
+    if (policy.require_heading_parity && removedHeadings.length) violations.push({ check: 'heading_parity', observed: removedHeadings.length, required: 0 });
+    if (policy.require_link_parity && removedLinks.length) violations.push({ check: 'link_parity', observed: removedLinks.length, required: 0 });
+    if (policy.require_structured_data_parity && !structuredDataMatches) violations.push({ check: 'structured_data_parity', observed: false, required: true });
+  }
+  return {
+    policy_id: policy?.policy_id || null,
+    review_owner: policy?.review_owner || null,
+    initial_text_hash: sha256(initial.text),
+    rendered_text_hash: sha256(rendered.text),
+    text_retention_ratio: textRetentionRatio,
+    removed_headings: removedHeadings,
+    added_headings: missing(rendered.headings, initial.headings),
+    removed_links: removedLinks,
+    added_links: missing(rendered.links, initial.links),
+    structured_data_matches: structuredDataMatches,
+    policy_violations: violations,
+    semantic_review_status: policy ? 'review_required' : 'not_evidenced',
+    interpretation_boundary: 'Deterministic parity and policy checks do not establish semantic, retrieval, citation, ranking, or business impact.',
+  };
+}

package/src/observations/sourceIdentity.js

@@ -0,0 +1,62 @@
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+export function buildSourceIdentityChain(registries) {
+  const entities = new Map((registries.entities?.entries || []).map((item) => [item.entity_id, item]));
+  const evidence = new Map((registries.evidence?.entries || []).map((item) => [item.evidence_id, item]));
+  const pages = (registries.pages?.entries || []).map((page) => {
+    const publisherEntity = entities.get(page.publisher_entity);
+    const publisher = publisherEntity ? {
+      entity_id: publisherEntity.entity_id,
+      name: publisherEntity.canonical_name,
+      canonical_url: publisherEntity.canonical_url || null,
+      status: publisherEntity.status,
+    } : null;
+    const authors = (page.author_entities || []).map((id) => {
+      const entity = entities.get(id);
+      return entity ? {
+        entity_id: entity.entity_id,
+        name: entity.canonical_name,
+        canonical_url: entity.canonical_url || null,
+        affiliations: (entity.affiliations || []).map((affiliation) => ({
+          ...affiliation,
+          entity_name: entities.get(affiliation.entity_id)?.canonical_name || null,
+        })),
+        status: entity.status,
+      } : { entity_id: id, name: null, canonical_url: null, affiliations: [], status: 'missing' };
+    });
+    const evidenceOwners = (page.evidence_references || []).map((id) => {
+      const item = evidence.get(id);
+      return { evidence_id: id, owner: item?.source_owner || null, verification_status: item?.verification_status || 'missing' };
+    });
+    const missing = [];
+    if (!publisher) missing.push('publisher_entity');
+    if (!authors.length) missing.push('author_entities');
+    else if (authors.some((author) => !author.affiliations.length)) missing.push('author_affiliations');
+    if (!page.content_owner) missing.push('content_owner');
+    if (!page.factual_reviewer) missing.push('factual_reviewer');
+    if (!page.correction_path) missing.push('correction_path');
+    if (evidenceOwners.some((item) => !item.owner)) missing.push('evidence_owner');
+    return {
+      page_id: page.page_id,
+      url: page.url,
+      publisher,
+      authors,
+      content_owner: page.content_owner || null,
+      factual_reviewer: page.factual_reviewer || null,
+      evidence_owners: evidenceOwners,
+      correction_path: page.correction_path || null,
+      status: missing.length ? 'incomplete' : 'complete',
+      missing_fields: [...new Set(missing)].sort(),
+    };
+  });
+  const chain = {
+    version: 1,
+    pages,
+    limitations: [
+      'Registry linkage records declared identity and governance relationships; it does not establish that disclosures are visible, current, independent, or recognized by external systems.',
+    ],
+  };
+  const check = validateAgainst('source-identity-chain.schema.json', chain);
+  if (!check.valid) throw new Error(`source identity chain violates contract: ${check.errors.join('; ')}`);
+  return chain;
+}