@nebulacomponents/citable 1.20.0 → 1.22.0

package/src/discovery/searchConsole.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 { providerRequest } from '../connectors/http.js';
+import { collectionResult, errorMessage } from '../connectors/collectionResult.js';
+
+const SEARCH_DATA_SCHEMA = 'search-discovery-data.schema.json';
+const BASE = 'https://www.googleapis.com/webmasters/v3';
+const DIMENSIONS = new Set(['date', 'query', 'page', 'country', 'device', 'searchAppearance']);
+const COLLECTOR = { id: 'citable-search-console-observations', version: '1.0.0' };
+const PARSER = { id: 'google-search-analytics-response', version: '1.0.0' };
+
+function assertDate(value, name) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`))) {
+    throw new TypeError(`${name} must be an ISO date (YYYY-MM-DD)`);
+  }
+}
+
+function validateRequest(request) {
+  if (!request || typeof request !== 'object' || Array.isArray(request)) throw new TypeError('Search Console request is required');
+  if (typeof request.property_id !== 'string' || !request.property_id) throw new TypeError('property_id is required');
+  assertDate(request.start_date, 'start_date');
+  assertDate(request.end_date, 'end_date');
+  if (request.start_date > request.end_date) throw new RangeError('start_date must not be after end_date');
+  const dimensions = request.dimensions ?? ['query', 'page'];
+  if (!Array.isArray(dimensions) || dimensions.length === 0 || dimensions.some((item) => !DIMENSIONS.has(item))) throw new TypeError('dimensions contain an unsupported Search Console dimension');
+  const filters = request.filters ?? {};
+  if (!filters || typeof filters !== 'object' || Array.isArray(filters)) throw new TypeError('filters must be an object');
+  const rowLimit = request.row_limit ?? 25000;
+  if (!Number.isInteger(rowLimit) || rowLimit < 1 || rowLimit > 25000) throw new RangeError('row_limit must be an integer from 1 to 25000');
+  return { property_id: request.property_id, start_date: request.start_date, end_date: request.end_date, dimensions: [...new Set(dimensions)], filters, row_limit: rowLimit };
+}
+
+function configurationFor(request) {
+  const configuration = { property_id: request.property_id, dimensions: request.dimensions, filters: request.filters, row_limit: request.row_limit };
+  return { id: `gsc-${sha256(canonicalEvidenceJson(configuration)).slice(0, 16)}`, version: '1.0.0' };
+}
+
+function numberOrNull(value) {
+  return value == null || value === '' || !Number.isFinite(Number(value)) ? null : Number(value);
+}
+
+function requestBody(request, startRow) {
+  const body = { startDate: request.start_date, endDate: request.end_date, dimensions: request.dimensions, rowLimit: request.row_limit, startRow, dataState: 'final' };
+  if (Object.keys(request.filters).length) body.dimensionFilterGroups = [{ groupType: 'and', filters: Object.entries(request.filters).map(([dimension, expression]) => ({ dimension, operator: 'equals', expression: String(expression) })) }];
+  return body;
+}
+
+function normalizeRow(row, request, dimensions, pageStart, coverageStatus, providerTotal, responseHash, origin) {
+  if (!row || !Array.isArray(row.keys)) throw new TypeError('Search Console row is malformed');
+  const values = Object.fromEntries(dimensions.map((name, index) => [name, row.keys[index] ?? null]));
+  const data = {
+    query: values.query ?? null,
+    page: values.page ?? null,
+    interval: { start_date: request.start_date, end_date: request.end_date },
+    metrics: { impressions: numberOrNull(row.impressions), clicks: numberOrNull(row.clicks), ctr: numberOrNull(row.ctr), average_position: numberOrNull(row.position) },
+    dimensions: { country: values.country ?? null, device: values.device ?? null, search_appearance: values.searchAppearance ?? null, date: values.date ?? null },
+    request: { property_id: request.property_id, dimensions: request.dimensions, filters: request.filters, row_limit: request.row_limit },
+    provider_reported: { row_count: providerTotal, page_start: pageStart },
+    coverage_status: coverageStatus,
+    response_hash: responseHash,
+    evidence_origin: origin,
+  };
+  const check = validateAgainst(SEARCH_DATA_SCHEMA, data);
+  if (!check.valid) throw new TypeError(`search discovery data violates contract: ${check.errors.join('; ')}`);
+  const subjectId = `query:${data.query ?? ''}|page:${data.page ?? ''}`;
+  return createExternalObservation({
+    observation_id: `GSC-${sha256(canonicalEvidenceJson({ request, values, row })).slice(0, 24)}`,
+    observation_type: 'EXTERNAL_OBSERVATION',
+    subject: { type: 'search_query_page', id: subjectId || `row:${pageStart}` },
+    source: { provider: 'google_search_console', method: 'search_analytics_api', authority: 'external_provider', account_or_property: request.property_id },
+    collector: COLLECTOR,
+    parser: PARSER,
+    configuration: configurationFor(request),
+    observed_at: nowIso(),
+    retrieved_at: nowIso(),
+    population: { declared: { id: `GSC-${sha256(canonicalEvidenceJson(request)).slice(0, 16)}`, size: providerTotal }, observed: 1, retrieved: 1, evaluated: 1, unavailable: 0, failed: 0 },
+    observation_status: coverageStatus === 'complete' ? 'observed' : 'incomplete',
+    retrieval_status: coverageStatus === 'complete' ? 'retrieved' : coverageStatus === 'indeterminate' ? 'indeterminate' : 'partial',
+    data,
+    lineage: { source_evidence: [responseHash] },
+    limitations: ['Search Console reports provider-returned search analytics rows, not universal search demand.', 'Provider privacy filtering, aggregation, and reporting revisions may limit representativeness.'],
+  });
+}
+
+/**
+ * Collect normalized Search Console search-analytics observations. This is a
+ * provider adapter: credentials are supplied only to the transport and are
+ * never written into observations or continuation state.
+ */
+export async function collectSearchConsoleObservations({ connection, request, token, fetchImpl = globalThis.fetch, maxPages = 1000, evidenceOrigin = 'LIVE_PROVIDER' } = {}) {
+  const normalized = validateRequest(request);
+  if (!['LIVE_PROVIDER', 'RECORDED_FIXTURE', 'SYNTHETIC_TEST'].includes(evidenceOrigin)) throw new TypeError('evidenceOrigin is invalid');
+  if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 10000) throw new RangeError('maxPages must be an integer from 1 to 10000');
+  if (connection?.property_id && connection.property_id !== normalized.property_id) throw new Error('connection property_id does not match request property_id');
+  const dimensions = normalized.dimensions;
+  const rows = [];
+  const observations = [];
+  const errors = [];
+  let startRow = 0;
+  let providerTotal = null;
+  let continuationState = null;
+  let pagesRequested = 0;
+  let pagesRetrieved = 0;
+  let lastResponseHash = null;
+  let response;
+  do {
+    pagesRequested += 1;
+    try {
+      response = await providerRequest(`${BASE}/sites/${encodeURIComponent(normalized.property_id)}/searchAnalytics/query`, {
+        token, fetchImpl, method: 'POST', body: requestBody(normalized, startRow),
+      });
+      if (!response || !Array.isArray(response.rows)) throw new Error('Search Console response rows must be an array');
+    } catch (error) {
+      errors.push(`start row ${startRow}: ${errorMessage(error)}`);
+      continuationState = { start_row: startRow };
+      break;
+    }
+    pagesRetrieved += 1;
+    lastResponseHash = sha256(canonicalEvidenceJson(response));
+    if (Number.isInteger(response.rowCount) && response.rowCount >= 0) providerTotal = response.rowCount;
+    rows.push(...response.rows.map((row) => ({ row, pageStart: startRow, responseHash: lastResponseHash })));
+    const moreRows = providerTotal !== null && rows.length < providerTotal;
+    if (providerTotal !== null && !moreRows) break;
+    if (providerTotal === null && response.rows.length < normalized.row_limit) break;
+    startRow += normalized.row_limit;
+    if (pagesRequested >= maxPages) {
+      continuationState = { start_row: startRow };
+      break;
+    }
+  } while (true);
+
+  const collection = collectionResult({
+    items: rows,
+    paginationState: { pages_requested: pagesRequested, pages_retrieved: pagesRetrieved, boundary: { max_pages: maxPages, row_limit: normalized.row_limit } },
+    providerReportedTotal: providerTotal,
+    continuationState,
+    providerCompleteness: providerTotal !== null ? 'declared' : 'unknown',
+    limitations: ['Search Console privacy filtering and aggregation apply.', 'A complete result is complete only for the declared API request; it is not a census of all search behavior.'],
+    errors,
+  });
+  const normalizedRows = rows.map(({ row, pageStart, responseHash }) => normalizeRow(row, normalized, dimensions, pageStart, collection.coverage_status, providerTotal, responseHash || sha256(canonicalEvidenceJson({ request: normalized, rows: [] })), evidenceOrigin));
+  observations.push(...normalizedRows);
+  return { observations, collection, request: normalized, provider: 'google_search_console', response_hash: lastResponseHash, errors };
+}
+
+export function compareSearchDiscoveryObservations(left, right) {
+  if (!verifyExternalObservation(left).valid || !verifyExternalObservation(right).valid) return { status: 'INDETERMINATE', dimensions: {}, limitations: ['Observation integrity could not be verified.'] };
+  const dimensions = {
+    provider: left.source.provider === right.source.provider ? 'match' : 'mismatch',
+    property: left.source.account_or_property === right.source.account_or_property ? 'match' : 'mismatch',
+    query: left.data.query === right.data.query ? 'match' : 'mismatch',
+    page: left.data.page === right.data.page ? 'match' : 'mismatch',
+    configuration: left.configuration?.id === right.configuration?.id ? 'match' : 'mismatch',
+    interval: JSON.stringify(left.data.interval) === JSON.stringify(right.data.interval) ? 'match' : 'mismatch',
+    coverage: left.data.coverage_status === right.data.coverage_status ? 'match' : 'mismatch',
+  };
+  const hardMismatch = ['provider', 'property', 'query', 'page', 'configuration'].some((key) => dimensions[key] === 'mismatch');
+  const incomplete = [left.data.coverage_status, right.data.coverage_status].some((status) => !['complete'].includes(status));
+  const status = hardMismatch ? 'NOT_COMPARABLE' : incomplete ? 'INDETERMINATE' : dimensions.interval === 'mismatch' ? 'PARTIALLY_COMPARABLE' : 'COMPARABLE';
+  return {
+    comparison_id: `GSC-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' ? [] : ['Search Console interval, configuration, and coverage limitations remain attached; no business opportunity or ranking conclusion is inferred.'],
+  };
+}
+
+function validSearchObservations(observations) {
+  return (Array.isArray(observations) ? observations : []).filter((item) => verifyExternalObservation(item).valid && item.source?.provider === 'google_search_console');
+}
+
+export function pagesForQuery(observations, query) {
+  return validSearchObservations(observations).filter((item) => item.data.query === query && item.data.page).map((item) => item);
+}
+
+export function queriesForPage(observations, page) {
+  return validSearchObservations(observations).filter((item) => item.data.page === page && item.data.query).map((item) => item);
+}
+
+export function relationshipObservations(observations, { query = null, page = null } = {}) {
+  return validSearchObservations(observations).filter((item) => (query == null || item.data.query === query) && (page == null || item.data.page === page));
+}

package/src/evidence/external.js

@@ -0,0 +1,251 @@
+import { canonicalEvidenceJson, createEvidenceHashes } from './hashes.js';
+import { sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const OBSERVATION_SCHEMA = 'external-observation.schema.json';
+const DATASET_SCHEMA = 'research-dataset.schema.json';
+const DERIVATION_SCHEMA = 'derivation.schema.json';
+const CLAIM_SCHEMA = 'claim-evidence.schema.json';
+const COMPARISON_SCHEMA = 'external-comparison.schema.json';
+const VERIFICATION_SCHEMA = 'claim-verification.schema.json';
+
+function without(value, key) {
+  const copy = { ...value };
+  delete copy[key];
+  return copy;
+}
+
+function integrity(value, key) {
+  return sha256(canonicalEvidenceJson(without(value, key)));
+}
+
+function validate(schema, value, label) {
+  const result = validateAgainst(schema, value);
+  if (!result.valid) throw new Error(`${label} violates contract: ${result.errors.join('; ')}`);
+  return value;
+}
+
+export function createExternalObservation(input) {
+  const item = { ...input };
+  item.evidence_hash = integrity(item, 'evidence_hash');
+  return validate(OBSERVATION_SCHEMA, item, 'external observation');
+}
+
+export function verifyExternalObservation(item) {
+  const failures = [];
+  const check = validateAgainst(OBSERVATION_SCHEMA, item);
+  if (!check.valid) failures.push(...check.errors);
+  if (item?.evidence_hash !== integrity(item || {}, 'evidence_hash')) failures.push('evidence hash is inconsistent');
+  return { valid: failures.length === 0, failures };
+}
+
+export function createResearchDataset(input, { previous = null } = {}) {
+  const item = { ...input };
+  item.dataset_hash = integrity(item, 'dataset_hash');
+  validate(DATASET_SCHEMA, item, 'research dataset');
+  if (previous && previous.dataset_id === item.dataset_id && previous.dataset_version === item.dataset_version
+    && previous.dataset_hash !== item.dataset_hash) {
+    throw new Error('research dataset version is immutable; create a new dataset_version');
+  }
+  return item;
+}
+
+export function verifyResearchDataset(item, { previous = null } = {}) {
+  const failures = [];
+  const check = validateAgainst(DATASET_SCHEMA, item);
+  if (!check.valid) failures.push(...check.errors);
+  if (item?.dataset_hash !== integrity(item || {}, 'dataset_hash')) failures.push('dataset hash is inconsistent');
+  if (previous && previous.dataset_id === item?.dataset_id && previous.dataset_version === item?.dataset_version
+    && previous.dataset_hash !== item?.dataset_hash) failures.push('research dataset version is immutable');
+  if (failures.length) throw new Error(`research dataset verification failed: ${failures.join('; ')}`);
+  return { valid: true, failures: [] };
+}
+
+export function createDerivation(input) {
+  const item = { ...input };
+  item.derivation_hash = integrity(item, 'derivation_hash');
+  return validate(DERIVATION_SCHEMA, item, 'derivation');
+}
+
+function verifyDerivation(item) {
+  const check = validateAgainst(DERIVATION_SCHEMA, item);
+  if (!check.valid || item.derivation_hash !== integrity(item, 'derivation_hash')) return false;
+  return true;
+}
+
+export function createEvidenceClaim(input) {
+  const item = { ...input };
+  item.claim_hash = integrity(item, 'claim_hash');
+  return validate(CLAIM_SCHEMA, item, 'claim evidence');
+}
+
+function verifyClaimIdentity(item) {
+  const check = validateAgainst(CLAIM_SCHEMA, item);
+  return check.valid && item.claim_hash === integrity(item, 'claim_hash');
+}
+
+function valueAt(object, path) {
+  return String(path).split('.').reduce((value, key) => value == null ? undefined : value[key], object);
+}
+
+function reason(code, message) {
+  return { code, message };
+}
+
+function evaluatePredicate(assertion, observations) {
+  if (!observations.length) return { status: 'NOT_OBSERVED', reasons: [reason('observation_missing', 'No referenced observation was available.')] };
+  const results = observations.map((item) => valueAt(item, assertion.path) === assertion.value);
+  if (results.every(Boolean)) return { status: 'SUPPORTED', reasons: [] };
+  if (results.some(Boolean)) return { status: 'PARTIALLY_SUPPORTED', reasons: [reason('predicate_partial', 'The predicate matched only part of the referenced population.')] };
+  return { status: 'CONTRADICTED', reasons: [reason('predicate_contradicted', 'In-scope evidence establishes an incompatible predicate value.')] };
+}
+
+function evaluateAssertion(assertion, observations, derivations) {
+  if (!assertion || typeof assertion !== 'object') return { status: 'INDETERMINATE', reasons: [reason('assertion_missing', 'The claim has no structured assertion.')] };
+  if (assertion.type === 'predicate' || assertion.type === 'all') return evaluatePredicate(assertion, observations);
+  if (assertion.type === 'count') {
+    const derivation = derivations[0];
+    if (!derivation || !verifyDerivation(derivation)) return { status: 'INDETERMINATE', reasons: [reason('derivation_unavailable', 'The referenced derivation is missing or unverifiable.')] };
+    if (derivation.result?.count === assertion.expected) return { status: 'SUPPORTED', reasons: [] };
+    return { status: 'CONTRADICTED', reasons: [reason('count_contradicted', 'The preserved derivation result differs from the claimed value.')] };
+  }
+  if (assertion.type === 'compound') {
+    const results = (assertion.assertions || []).map((part) => evaluateAssertion(part, observations, derivations));
+    if (!results.length) return { status: 'INDETERMINATE', reasons: [reason('compound_empty', 'The compound claim has no components.')] };
+    const reasons = results.flatMap((item) => item.reasons);
+    if (results.every((item) => item.status === 'SUPPORTED')) return { status: 'SUPPORTED', reasons };
+    if (results.some((item) => item.status === 'CONTRADICTED')) return { status: 'PARTIALLY_SUPPORTED', reasons: [...reasons, reason('compound_component_unsupported', 'At least one compound component is contradicted.')] };
+    if (results.some((item) => item.status === 'SUPPORTED')) return { status: 'PARTIALLY_SUPPORTED', reasons: [...reasons, reason('compound_component_unsupported', 'At least one compound component is unsupported.')] };
+    return { status: results.some((item) => item.status === 'NOT_OBSERVED') ? 'NOT_OBSERVED' : 'UNSUPPORTED', reasons };
+  }
+  return { status: 'INDETERMINATE', reasons: [reason('assertion_unsupported', `Assertion type ${assertion.type || 'unknown'} is not supported.`)] };
+}
+
+function scopeSupport(claim, datasets, observations) {
+  const scope = claim.declared_scope;
+  if (scope.generalization === 'universal') return { status: 'UNSUPPORTED', reasons: [reason('generalization_outside_population', 'The evidence population does not support a universal claim.')] };
+  if (scope.type === 'observation' && scope.observation_reference
+    && !(claim.observation_references || []).includes(scope.observation_reference)) {
+    return { status: 'INDETERMINATE', reasons: [reason('scope_reference_mismatch', 'The declared observation scope is not among the claim evidence references.')] };
+  }
+  if (scope.type === 'dataset' && scope.dataset_reference
+    && !(claim.dataset_references || []).includes(scope.dataset_reference)) {
+    return { status: 'INDETERMINATE', reasons: [reason('scope_reference_mismatch', 'The declared dataset scope is not among the claim evidence references.')] };
+  }
+  if (scope.type === 'dataset') {
+    const dataset = datasets[0];
+    if (!dataset || !verifyDatasetSafe(dataset)) return { status: 'INDETERMINATE', reasons: [reason('dataset_unavailable', 'The declared dataset is missing or unverifiable.')] };
+    if (dataset.coverage_status !== 'complete_for_declared_population') return { status: 'PARTIALLY_SUPPORTED', reasons: [reason('dataset_coverage_incomplete', `Dataset coverage is ${dataset.coverage_status}, not complete for the declared population.`)] };
+    const referenced = new Set(claim.observation_references || []);
+    const missingMembers = (dataset.observation_references || []).filter((id) => !referenced.has(id));
+    if (missingMembers.length) return { status: 'PARTIALLY_SUPPORTED', reasons: [reason('dataset_members_missing', `The claim does not reference every observation in the declared dataset: ${missingMembers.join(', ')}`)] };
+  }
+  if (!observations.length) return { status: 'NOT_OBSERVED', reasons: [reason('observation_missing', 'The declared scope has no observed members.')] };
+  return { status: 'SUPPORTED', reasons: [] };
+}
+
+function verifyDatasetSafe(dataset) {
+  try { return verifyResearchDataset(dataset).valid; } catch { return false; }
+}
+
+function datasetReference(dataset) {
+  return `${dataset.dataset_id}@${dataset.dataset_version}`;
+}
+
+function resolveDatasetReference(reference, datasets) {
+  const exact = datasets.filter((item) => datasetReference(item) === reference);
+  if (exact.length === 1) return exact[0];
+  // Legacy id-only references remain valid only while the id has one version.
+  // Once versions diverge, silently selecting one would rewrite historical
+  // claim meaning.
+  if (!String(reference).includes('@')) {
+    const byId = datasets.filter((item) => item.dataset_id === reference);
+    return byId.length === 1 ? byId[0] : null;
+  }
+  return null;
+}
+
+function combine(proposition, scope) {
+  if (proposition.status === 'NOT_OBSERVED') return 'NOT_OBSERVED';
+  if (proposition.status === 'INDETERMINATE' || scope.status === 'INDETERMINATE') return 'INDETERMINATE';
+  if (proposition.status === 'CONTRADICTED') return 'CONTRADICTED';
+  if (proposition.status === 'PARTIALLY_SUPPORTED' || scope.status === 'PARTIALLY_SUPPORTED' || scope.status === 'UNSUPPORTED') return 'PARTIALLY_SUPPORTED';
+  if (proposition.status === 'UNSUPPORTED') return 'UNSUPPORTED';
+  return 'SUPPORTED';
+}
+
+export function verifyClaim(claim, { observations = [], datasets = [], derivations = [] } = {}) {
+  if (!verifyClaimIdentity(claim)) {
+    return {
+      claim_id: claim?.claim_id || 'unknown', claim_version: claim?.claim_version || 1,
+      overall: 'INDETERMINATE', proposition_support: 'INDETERMINATE', scope_support: 'INDETERMINATE',
+      reasons: [reason('claim_unverifiable', 'Claim identity, schema, or integrity hash could not be verified.')],
+      lineage: { claim_reference: claim?.claim_id || 'unknown', observation_references: claim?.observation_references || [], dataset_references: claim?.dataset_references || [], derivation_references: claim?.derivation_references || [] }, limitations: ['Claim evidence could not be verified.'],
+    };
+  }
+  const byId = new Map(observations.map((item) => [item.observation_id, item]));
+  const referenced = (claim.observation_references || []).map((id) => byId.get(id)).filter(Boolean);
+  const missing = (claim.observation_references || []).filter((id) => !byId.has(id));
+  const integrityFailure = referenced.some((item) => !verifyExternalObservation(item).valid);
+  let proposition;
+  if (integrityFailure) proposition = { status: 'INDETERMINATE', reasons: [reason('evidence_unverifiable', 'Referenced observation integrity verification failed.')] };
+  else if (missing.length) proposition = { status: 'NOT_OBSERVED', reasons: [reason('observation_missing', `Missing referenced observations: ${missing.join(', ')}`)] };
+  else proposition = evaluateAssertion(claim.assertion, referenced, (claim.derivation_references || []).map((id) => derivations.find((item) => item.derivation_id === id)).filter(Boolean));
+  const selectedDatasets = (claim.dataset_references || []).map((reference) => resolveDatasetReference(reference, datasets)).filter(Boolean);
+  const missingDatasets = (claim.dataset_references || []).filter((reference) => !resolveDatasetReference(reference, datasets));
+  const scope = scopeSupport(claim, selectedDatasets, referenced);
+  if (missingDatasets.length && claim.declared_scope.type === 'dataset') {
+    scope.status = 'INDETERMINATE';
+    scope.reasons.push(reason('dataset_reference_ambiguous_or_missing', `Dataset references could not be resolved exactly: ${missingDatasets.join(', ')}`));
+  }
+  const result = {
+    claim_id: claim.claim_id, claim_version: claim.claim_version, overall: combine(proposition, scope),
+    proposition_support: proposition.status, scope_support: scope.status,
+    reasons: [...proposition.reasons, ...scope.reasons],
+    lineage: { claim_reference: claim.claim_id, observation_references: claim.observation_references || [], dataset_references: claim.dataset_references || [], derivation_references: claim.derivation_references || [] },
+    limitations: claim.limitations || [],
+  };
+  return validate(VERIFICATION_SCHEMA, result, 'claim verification');
+}
+
+const COMPARISON_DIMENSIONS = ['source', 'subject', 'collector', 'parser', 'configuration', 'population', 'normalization', 'dataset_version', 'derivation_version'];
+
+function dimensionValue(item, dimension) {
+  if (dimension === 'source') return item.source?.provider;
+  if (dimension === 'subject') return item.subject?.id;
+  if (dimension === 'collector') return `${item.collector?.id || ''}@${item.collector?.version || ''}` || null;
+  if (dimension === 'parser') return item.parser ? `${item.parser.id}@${item.parser.version}` : null;
+  if (dimension === 'configuration') return item.configuration ? `${item.configuration.id}@${item.configuration.version}` : null;
+  if (dimension === 'population') return item.population?.declared?.id || item.declared_population?.id;
+  if (dimension === 'normalization') return item.normalization ? `${item.normalization.method}@${item.normalization.version}` : null;
+  if (dimension === 'dataset_version') return item.dataset_id ? `${item.dataset_id}@${item.dataset_version}` : null;
+  if (dimension === 'derivation_version') return item.derivation_id ? `${item.derivation_id}@${item.derivation_version}` : null;
+  return null;
+}
+
+function compareItems(left, right, leftReference, rightReference, dimensionsToCompare = COMPARISON_DIMENSIONS) {
+  const dimensions = {};
+  for (const key of dimensionsToCompare) {
+    const a = dimensionValue(left, key); const b = dimensionValue(right, key);
+    dimensions[key] = a == null || b == null ? 'missing' : a === b ? 'match' : 'mismatch';
+  }
+  const mismatches = Object.values(dimensions).filter((x) => x === 'mismatch').length;
+  const missing = Object.values(dimensions).filter((x) => x === 'missing').length;
+  const status = mismatches ? 'NOT_COMPARABLE' : missing ? 'PARTIALLY_COMPARABLE' : 'COMPARABLE';
+  const result = { comparison_id: `CMP-${sha256(canonicalEvidenceJson({ leftReference, rightReference, dimensions })).slice(0, 16)}`, left_reference: leftReference, right_reference: rightReference, status, dimensions, limitations: status === 'COMPARABLE' ? [] : ['No delta should be generalized beyond the aligned dimensions.'] };
+  return validate(COMPARISON_SCHEMA, result, 'external comparison');
+}
+
+export function compareExternalObservations(left, right) {
+  if (!verifyExternalObservation(left).valid || !verifyExternalObservation(right).valid) {
+    return { comparison_id: `CMP-${sha256(`${left?.observation_id || ''}:${right?.observation_id || ''}`).slice(0, 16)}`, left_reference: left?.observation_id || 'unknown', right_reference: right?.observation_id || 'unknown', status: 'INDETERMINATE', dimensions: {}, limitations: ['Observation integrity could not be verified.'] };
+  }
+  return compareItems(left, right, left.observation_id, right.observation_id,
+    ['source', 'subject', 'collector', 'parser', 'configuration', 'population']);
+}
+
+export function compareResearchDatasets(left, right) {
+  if (!verifyDatasetSafe(left) || !verifyDatasetSafe(right)) return { comparison_id: 'CMP-invalid', left_reference: left?.dataset_id || 'unknown', right_reference: right?.dataset_id || 'unknown', status: 'INDETERMINATE', dimensions: {}, limitations: ['Dataset integrity could not be verified.'] };
+  return compareItems(left, right, `${left.dataset_id}@${left.dataset_version}`, `${right.dataset_id}@${right.dataset_version}`,
+    ['dataset_version', 'normalization', 'population']);
+}

package/src/representation/competitors.js

@@ -0,0 +1,113 @@
+import { createExternalObservation, verifyExternalObservation, compareExternalObservations } from '../evidence/external.js';
+import { canonicalEvidenceJson } from '../evidence/hashes.js';
+import { sha256, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import { createResponseSpan } from './provenance.js';
+
+const SCHEMA = 'competitor-representation.schema.json';
+const COLLECTOR = { id: 'citable-competitor-representation', version: '1.0.0' };
+const PARSER = { id: 'provider-neutral-competitor-parser', version: '1.0.0' };
+const TYPES = new Set(['MENTION', 'COMPARISON', 'ALTERNATIVE', 'RECOMMENDATION', 'CITED_SOURCE', 'CATEGORY_PEER']);
+
+function validate(value) {
+  const result = validateAgainst(SCHEMA, value);
+  if (!result.valid) throw new TypeError(`competitor representation violates contract: ${result.errors.join('; ')}`);
+  return value;
+}
+
+function requireExecution(execution) {
+  if (!execution?.observation_id || !verifyExternalObservation(execution).valid) throw new TypeError('competitor representation requires a verified execution');
+  if (execution.data?.response?.status !== 'succeeded') throw new Error('competitor representation requires a substantive provider response');
+}
+
+/** Preserve observed entity identity; no name-only resolution is performed. */
+export function resolveObservedEntity({ observedName, domain = null, entityId = null, resolutionMethod = 'not_resolved' } = {}) {
+  if (typeof observedName !== 'string' || !observedName.trim()) throw new TypeError('observedName is required');
+  const resolved = Boolean(entityId);
+  return {
+    entity_id: entityId || null,
+    observed_name: observedName,
+    domain: domain || null,
+    resolution_status: resolved ? 'RESOLVED' : 'AMBIGUOUS',
+    resolution_method: resolutionMethod,
+  };
+}
+
+export function createCompetitorRepresentationObservation({ execution, span, entity, representation, citationReference = null, propositionReference = null, evidenceOrigin = 'RECORDED_FIXTURE', observedAt = nowIso(), limitations = [] } = {}) {
+  requireExecution(execution);
+  const responseSpan = span?.span_id ? span : createResponseSpan({ execution, ...(span || {}) });
+  if (responseSpan.execution_reference !== execution.observation_id) throw new Error('competitor span does not belong to execution');
+  if (!entity?.observed_name) throw new TypeError('competitor entity observation is required');
+  if (!representation?.type || !TYPES.has(representation.type) || !representation.observed_text) throw new TypeError('competitor representation type and observed_text are required');
+  if (!['LIVE_PROVIDER', 'RECORDED_FIXTURE', 'SYNTHETIC_TEST'].includes(evidenceOrigin)) throw new TypeError('evidenceOrigin is invalid');
+  const data = validate({
+    execution_reference: execution.observation_id,
+    provider: execution.data.provider,
+    prompt_reference: `${execution.data.prompt_set.prompt_set_id}@${execution.data.prompt_set.prompt_set_version}:${execution.data.prompt.prompt_id}`,
+    prompt_set_reference: `${execution.data.prompt_set.prompt_set_id}@${execution.data.prompt_set.prompt_set_version}`,
+    span: responseSpan,
+    entity: {
+      entity_id: entity.entity_id || null,
+      observed_name: entity.observed_name,
+      domain: entity.domain || null,
+      resolution_status: entity.resolution_status || (entity.entity_id ? 'RESOLVED' : 'AMBIGUOUS'),
+      resolution_method: entity.resolution_method || 'not_resolved',
+    },
+    representation: { type: representation.type, observed_text: representation.observed_text },
+    citation_reference: citationReference,
+    proposition_reference: propositionReference,
+  });
+  const identity = data.entity.entity_id || `AMBIGUOUS-${sha256(canonicalEvidenceJson({ execution: execution.observation_id, span: responseSpan.span_id, name: data.entity.observed_name, domain: data.entity.domain })).slice(0, 24)}`;
+  return createExternalObservation({
+    observation_id: `ENT-${sha256(canonicalEvidenceJson({ execution: execution.observation_id, data })).slice(0, 24)}`,
+    observation_type: 'EXTERNAL_OBSERVATION',
+    subject: { type: 'competitor_representation', id: identity },
+    source: { provider: execution.data.provider, method: 'competitor_representation_observation', authority: 'external_provider' },
+    collector: COLLECTOR,
+    parser: PARSER,
+    configuration: execution.data.execution.configuration,
+    observed_at: observedAt,
+    retrieved_at: observedAt,
+    executed_at: execution.data.execution.executed_at,
+    population: { declared: execution.population?.declared || null, observed: 1, retrieved: 1, evaluated: 1, unavailable: 0, failed: 0 },
+    observation_status: 'observed',
+    retrieval_status: 'retrieved',
+    data: { ...data, evidence_origin: evidenceOrigin },
+    lineage: { source_evidence: [execution.observation_id], predecessor_references: [execution.observation_id], package_reference: null },
+    limitations: [...new Set(limitations)],
+  });
+}
+
+export function verifyCompetitorRepresentationObservation(item) {
+  return verifyExternalObservation(item);
+}
+
+export function representationsForEntity(observations, entityId) {
+  return (observations || []).filter((item) => item.data?.entity?.entity_id === entityId);
+}
+
+export function representationsForExecution(observations, executionId) {
+  return (observations || []).filter((item) => item.data?.execution_reference === executionId);
+}
+
+/** Comparability is inherited from the common external evidence contract. */
+export function compareCompetitorRepresentations(left, right) {
+  const base = compareExternalObservations(left, right);
+  if (!verifyCompetitorRepresentationObservation(left).valid || !verifyCompetitorRepresentationObservation(right).valid) return base;
+  const dimensions = {
+    ...base.dimensions,
+    prompt: left.data.prompt_reference === right.data.prompt_reference ? 'match' : 'mismatch',
+    prompt_set: left.data.prompt_set_reference === right.data.prompt_set_reference ? 'match' : 'mismatch',
+    representation_type: left.data.representation.type === right.data.representation.type ? 'match' : 'mismatch',
+    entity_resolution: left.data.entity.resolution_method === right.data.entity.resolution_method && left.data.entity.resolution_status === right.data.entity.resolution_status ? 'match' : 'mismatch',
+  };
+  const mismatched = Object.values(dimensions).some((value) => value === 'mismatch');
+  const missing = Object.values(dimensions).some((value) => value === 'missing');
+  return {
+    ...base,
+    comparison_id: `CMP-${sha256(canonicalEvidenceJson({ left: left.observation_id, right: right.observation_id, dimensions })).slice(0, 16)}`,
+    status: mismatched ? 'NOT_COMPARABLE' : missing ? 'PARTIALLY_COMPARABLE' : 'COMPARABLE',
+    dimensions,
+    limitations: mismatched || missing ? ['Representation type, entity resolution, prompt identity, and population must align before a delta is interpreted.'] : [],
+  };
+}