@nebulacomponents/citable 1.21.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",

package/schemas/citation-provenance.schema.json

@@ -0,0 +1,59 @@
+{
+  "$id": "citable://schemas/citation-provenance.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Provider citation provenance observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["execution_reference", "response_reference", "provider", "span", "citation", "source", "retrieval", "proposition", "support"],
+  "properties": {
+    "execution_reference": { "type": "string", "minLength": 1 },
+    "response_reference": { "type": "string", "minLength": 1 },
+    "provider": { "type": "string", "minLength": 1 },
+    "span": { "$ref": "citable://schemas/response-span.schema.json" },
+    "citation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["citation_id", "ordinal", "raw_marker", "placement", "displayed_title", "displayed_domain", "displayed_url"],
+      "properties": {
+        "citation_id": { "type": "string", "minLength": 1 },
+        "ordinal": { "type": "integer", "minimum": 1 },
+        "raw_marker": { "type": ["string", "null"] },
+        "placement": { "type": "string", "enum": ["inline", "footnote", "card", "source_list", "unknown"] },
+        "displayed_title": { "type": ["string", "null"] },
+        "displayed_domain": { "type": ["string", "null"] },
+        "displayed_url": { "type": ["string", "null"] }
+      }
+    },
+    "source": {
+      "type": "object", "additionalProperties": false,
+      "required": ["identity_status", "resolved_url", "redirect_chain", "canonical_url"],
+      "properties": {
+        "identity_status": { "type": "string", "enum": ["IDENTIFIED", "NOT_IDENTIFIED", "AMBIGUOUS"] },
+        "resolved_url": { "type": ["string", "null"], "format": "uri" },
+        "redirect_chain": { "type": "array", "items": { "type": "string", "format": "uri" } },
+        "canonical_url": { "type": ["string", "null"], "format": "uri" }
+      }
+    },
+    "retrieval": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "observation_reference"],
+      "properties": {
+        "status": { "type": "string", "enum": ["NOT_ATTEMPTED", "ATTEMPTED", "SUCCEEDED", "FAILED", "INDETERMINATE"] },
+        "observation_reference": { "type": ["string", "null"] }
+      }
+    },
+    "proposition": {
+      "type": "object", "additionalProperties": false,
+      "required": ["proposition_id", "text"],
+      "properties": { "proposition_id": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1 } }
+    },
+    "support": {
+      "type": "object", "additionalProperties": false,
+      "required": ["relevance_status", "support_status", "evidence_references"],
+      "properties": {
+        "relevance_status": { "type": "string", "enum": ["NOT_ASSESSED", "RELEVANT", "IRRELEVANT", "INDETERMINATE"] },
+        "support_status": { "type": "string", "enum": ["NOT_ASSESSED", "SUPPORTED", "PARTIALLY_SUPPORTED", "UNSUPPORTED", "CONTRADICTED", "INDETERMINATE", "NOT_OBSERVED"] },
+        "evidence_references": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/competitor-representation.schema.json

@@ -0,0 +1,36 @@
+{
+  "$id": "citable://schemas/competitor-representation.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Competitor or peer representation observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["execution_reference", "provider", "prompt_reference", "prompt_set_reference", "span", "entity", "representation", "citation_reference", "proposition_reference"],
+  "properties": {
+    "execution_reference": { "type": "string", "minLength": 1 },
+    "provider": { "type": "string", "minLength": 1 },
+    "prompt_reference": { "type": "string", "minLength": 1 },
+    "prompt_set_reference": { "type": "string", "minLength": 1 },
+    "span": { "$ref": "citable://schemas/response-span.schema.json" },
+    "entity": {
+      "type": "object", "additionalProperties": false,
+      "required": ["entity_id", "observed_name", "domain", "resolution_status", "resolution_method"],
+      "properties": {
+        "entity_id": { "type": ["string", "null"] },
+        "observed_name": { "type": "string", "minLength": 1 },
+        "domain": { "type": ["string", "null"] },
+        "resolution_status": { "type": "string", "enum": ["RESOLVED", "AMBIGUOUS", "UNRESOLVED", "NOT_OBSERVED"] },
+        "resolution_method": { "type": "string", "minLength": 1 }
+      }
+    },
+    "representation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["type", "observed_text"],
+      "properties": {
+        "type": { "type": "string", "enum": ["MENTION", "COMPARISON", "ALTERNATIVE", "RECOMMENDATION", "CITED_SOURCE", "CATEGORY_PEER"] },
+        "observed_text": { "type": "string", "minLength": 1 }
+      }
+    },
+    "citation_reference": { "type": ["string", "null"] },
+    "proposition_reference": { "type": ["string", "null"] }
+  }
+}

package/schemas/response-span.schema.json

@@ -0,0 +1,16 @@
+{
+  "$id": "citable://schemas/response-span.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Immutable provider response span",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["span_id", "execution_reference", "start", "end", "text", "text_hash"],
+  "properties": {
+    "span_id": { "type": "string", "minLength": 1 },
+    "execution_reference": { "type": "string", "minLength": 1 },
+    "start": { "type": "integer", "minimum": 0 },
+    "end": { "type": "integer", "minimum": 0 },
+    "text": { "type": "string" },
+    "text_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/source-retrieval.schema.json

@@ -0,0 +1,41 @@
+{
+  "$id": "citable://schemas/source-retrieval.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Retrieved citation source observation data",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["citation_reference", "url", "retrieval", "content", "relevance"],
+  "properties": {
+    "citation_reference": { "type": "string", "minLength": 1 },
+    "url": { "type": "string", "format": "uri" },
+    "retrieval": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "attempted_at", "final_url", "redirect_chain", "http_status"],
+      "properties": {
+        "status": { "type": "string", "enum": ["SUCCEEDED", "FAILED", "INDETERMINATE"] },
+        "attempted_at": { "type": "string", "format": "date-time" },
+        "final_url": { "type": ["string", "null"], "format": "uri" },
+        "redirect_chain": { "type": "array", "items": { "type": "string", "format": "uri" } },
+        "http_status": { "type": ["integer", "null"], "minimum": 100, "maximum": 599 }
+      }
+    },
+    "content": {
+      "type": "object", "additionalProperties": false,
+      "required": ["observed", "content_hash", "raw_retained"],
+      "properties": {
+        "observed": { "type": "boolean" },
+        "content_hash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+        "raw_retained": { "type": "boolean" }
+      }
+    },
+    "relevance": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "support_status", "evidence_references"],
+      "properties": {
+        "status": { "type": "string", "enum": ["NOT_ASSESSED", "RELEVANT", "IRRELEVANT", "INDETERMINATE"] },
+        "support_status": { "type": "string", "enum": ["NOT_ASSESSED", "SUPPORTED", "PARTIALLY_SUPPORTED", "UNSUPPORTED", "CONTRADICTED", "INDETERMINATE", "NOT_OBSERVED"] },
+        "evidence_references": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.21.0
+version: 1.22.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness

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.'] : [],
+  };
+}

package/src/representation/provenance.js

@@ -0,0 +1,214 @@
+import { createExternalObservation, createDerivation, verifyExternalObservation, verifyClaim } from '../evidence/external.js';
+import { canonicalEvidenceJson } from '../evidence/hashes.js';
+import { sha256, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const SPAN_SCHEMA = 'response-span.schema.json';
+const CITATION_SCHEMA = 'citation-provenance.schema.json';
+const SOURCE_SCHEMA = 'source-retrieval.schema.json';
+const COLLECTOR = { id: 'citable-citation-provenance', version: '1.0.0' };
+const PARSER = { id: 'provider-neutral-citation-parser', version: '1.0.0' };
+
+function validate(schema, value, label) {
+  const result = validateAgainst(schema, value);
+  if (!result.valid) throw new TypeError(`${label} violates contract: ${result.errors.join('; ')}`);
+  return value;
+}
+
+function validUrl(value) {
+  try { return new URL(value).toString(); } catch { return null; }
+}
+
+function executionReference(execution) {
+  if (!execution?.observation_id || !verifyExternalObservation(execution).valid) {
+    throw new TypeError('citation execution must be a verified external observation');
+  }
+  if (execution.data?.response?.status !== 'succeeded') throw new Error('citation requires a substantive provider response');
+  return execution.observation_id;
+}
+
+/** Create a stable, exact text span without normalizing provider prose. */
+export function createResponseSpan({ execution, start, end, text, spanId = null } = {}) {
+  const executionId = execution?.observation_id || execution;
+  if (typeof executionId !== 'string' || !executionId) throw new TypeError('execution reference is required');
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start) throw new TypeError('span offsets are invalid');
+  if (typeof text !== 'string') throw new TypeError('span text is required');
+  if (end - start !== text.length) throw new TypeError('span offsets must bound the exact response text');
+  const item = {
+    span_id: spanId || `SPAN-${sha256(canonicalEvidenceJson({ execution_reference: executionId, start, end, text })).slice(0, 24)}`,
+    execution_reference: executionId,
+    start,
+    end,
+    text,
+    text_hash: sha256(text),
+  };
+  return validate(SPAN_SCHEMA, item, 'response span');
+}
+
+function sourceShape(citation, source = {}) {
+  const displayed = citation.displayed_url ?? citation.url ?? null;
+  const resolved = validUrl(source.resolved_url ?? citation.resolved_url);
+  const status = source.identity_status || (resolved ? 'IDENTIFIED' : displayed ? 'AMBIGUOUS' : 'NOT_IDENTIFIED');
+  return {
+    identity_status: status,
+    resolved_url: resolved,
+    redirect_chain: (source.redirect_chain || []).map(validUrl).filter(Boolean),
+    canonical_url: validUrl(source.canonical_url) || null,
+  };
+}
+
+function citationData({ execution, span, citation, proposition, source, retrieval, support }) {
+  const data = {
+    execution_reference: execution.observation_id,
+    response_reference: execution.data.response.response_hash,
+    provider: execution.data.provider,
+    span,
+    citation: {
+      citation_id: citation.citation_id || `CIT-${sha256(canonicalEvidenceJson({ execution: execution.observation_id, span: span.span_id, ordinal: citation.ordinal || 1, marker: citation.raw_marker || null })).slice(0, 24)}`,
+      ordinal: citation.ordinal || 1,
+      raw_marker: citation.raw_marker ?? null,
+      placement: citation.placement || 'unknown',
+      displayed_title: citation.displayed_title ?? citation.title ?? null,
+      displayed_domain: citation.displayed_domain ?? citation.domain ?? null,
+      displayed_url: citation.displayed_url ?? citation.url ?? null,
+    },
+    source: sourceShape(citation, source),
+    retrieval: { status: retrieval?.status || 'NOT_ATTEMPTED', observation_reference: retrieval?.observation_reference || null },
+    proposition: { proposition_id: proposition?.proposition_id || `PROP-${sha256(proposition?.text || span.text).slice(0, 24)}`, text: proposition?.text || span.text },
+    support: {
+      relevance_status: support?.relevance_status || 'NOT_ASSESSED',
+      support_status: support?.support_status || 'NOT_ASSESSED',
+      evidence_references: [...new Set(support?.evidence_references || [])],
+    },
+  };
+  return validate(CITATION_SCHEMA, data, 'citation provenance');
+}
+
+/** Create an immutable citation linked to one exact response span. */
+export function createCitationObservation({ execution, span, citation, proposition, source = {}, retrieval = null, support = null, evidenceOrigin = 'RECORDED_FIXTURE', observedAt = nowIso(), limitations = [] } = {}) {
+  executionReference(execution);
+  const responseSpan = span?.span_id ? validate(SPAN_SCHEMA, span, 'response span') : createResponseSpan({ execution, ...(span || {}) });
+  if (responseSpan.execution_reference !== execution.observation_id) throw new Error('span does not belong to execution');
+  const data = citationData({ execution, span: responseSpan, citation: citation || {}, proposition, source, retrieval, support });
+  if (!['LIVE_PROVIDER', 'RECORDED_FIXTURE', 'SYNTHETIC_TEST'].includes(evidenceOrigin)) throw new TypeError('evidenceOrigin is invalid');
+  return createExternalObservation({
+    observation_id: `CIT-${sha256(canonicalEvidenceJson({ execution: execution.observation_id, data })).slice(0, 24)}`,
+    observation_type: 'EXTERNAL_OBSERVATION',
+    subject: { type: 'citation', id: data.citation.citation_id },
+    source: { provider: execution.data.provider, method: 'citation_provenance', 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)],
+  });
+}
+
+/** Build a set while refusing duplicate citation ordinals or identifiers. */
+export function createCitationObservations(input = {}) {
+  const citations = input.citations || [];
+  const ids = new Set(), ordinals = new Set();
+  return citations.map((citation) => {
+    const item = createCitationObservation({ ...input, citation });
+    const id = item.data.citation.citation_id;
+    const ordinal = item.data.citation.ordinal;
+    if (ids.has(id)) throw new Error(`duplicate citation_id: ${id}`);
+    if (ordinals.has(ordinal)) throw new Error(`duplicate citation ordinal: ${ordinal}`);
+    ids.add(id); ordinals.add(ordinal);
+    return item;
+  });
+}
+
+export function verifyCitationObservation(item) {
+  return verifyExternalObservation(item);
+}
+
+/** Preserve source retrieval as a separate observation; failed retrieval is never support failure. */
+export function createSourceRetrievalObservation({ citation, url, status = 'SUCCEEDED', body = null, finalUrl = null, redirectChain = [], httpStatus = null, attemptedAt = nowIso(), relevanceStatus = 'NOT_ASSESSED', supportStatus = 'NOT_ASSESSED', evidenceReferences = [], rawRetained = false, evidenceOrigin = 'RECORDED_FIXTURE', limitations = [] } = {}) {
+  if (!citation?.observation_id || !verifyCitationObservation(citation).valid) throw new TypeError('citation must be a verified citation observation');
+  const sourceUrl = validUrl(url || citation.data.source.resolved_url);
+  if (!sourceUrl) throw new TypeError('retrieval URL must be a valid URL');
+  const contentHash = body == null ? null : sha256(body);
+  const data = validate(SOURCE_SCHEMA, {
+    citation_reference: citation.observation_id,
+    url: sourceUrl,
+    retrieval: { status, attempted_at: attemptedAt, final_url: validUrl(finalUrl) || (status === 'SUCCEEDED' ? sourceUrl : null), redirect_chain: redirectChain.map(validUrl).filter(Boolean), http_status: status === 'SUCCEEDED' ? (httpStatus || 200) : httpStatus },
+    content: { observed: status === 'SUCCEEDED' && body != null, content_hash: contentHash, raw_retained: Boolean(rawRetained) },
+    relevance: { status: relevanceStatus, support_status: supportStatus, evidence_references: [...new Set(evidenceReferences)] },
+  }, 'source retrieval');
+  return createExternalObservation({
+    observation_id: `SRC-${sha256(canonicalEvidenceJson({ citation: citation.observation_id, data })).slice(0, 24)}`,
+    observation_type: 'EXTERNAL_OBSERVATION',
+    subject: { type: 'citation_source', id: sourceUrl },
+    source: { provider: citation.data.provider, method: 'citation_source_retrieval', authority: 'third_party' },
+    collector: COLLECTOR,
+    parser: PARSER,
+    configuration: null,
+    observed_at: attemptedAt,
+    retrieved_at: attemptedAt,
+    executed_at: null,
+    population: { declared: null, observed: status === 'SUCCEEDED' ? 1 : 0, retrieved: status === 'SUCCEEDED' ? 1 : 0, evaluated: status === 'SUCCEEDED' ? 1 : 0, unavailable: 0, failed: status === 'FAILED' ? 1 : 0 },
+    observation_status: status === 'SUCCEEDED' ? 'observed' : status === 'FAILED' ? 'failed' : 'indeterminate',
+    retrieval_status: status === 'SUCCEEDED' ? 'retrieved' : status === 'FAILED' ? 'failed' : 'indeterminate',
+    data: { ...data, evidence_origin: evidenceOrigin },
+    lineage: { source_evidence: [citation.observation_id], predecessor_references: [citation.observation_id], package_reference: null },
+    limitations: [...new Set([...(status === 'FAILED' ? ['Source retrieval failed; proposition support is indeterminate.'] : []), ...limitations])],
+  });
+}
+
+export function verifySourceRetrievalObservation(item) {
+  return verifyExternalObservation(item);
+}
+
+export function assessPropositionSupport({ retrieval, relevanceStatus, supportStatus, evidenceReferences = [] } = {}) {
+  if (!retrieval || !verifySourceRetrievalObservation(retrieval).valid) return { status: 'INDETERMINATE', reasons: ['source retrieval evidence is missing or unverifiable'], evidence_references: [] };
+  if (retrieval.data.retrieval.status !== 'SUCCEEDED') return { status: 'INDETERMINATE', reasons: ['source retrieval did not succeed'], evidence_references: [retrieval.observation_id] };
+  if (relevanceStatus === 'IRRELEVANT') return { status: 'UNSUPPORTED', reasons: ['retrieved source was assessed as irrelevant to the proposition'], evidence_references: [retrieval.observation_id, ...evidenceReferences] };
+  const supportedStates = new Set(['SUPPORTED', 'PARTIALLY_SUPPORTED', 'UNSUPPORTED', 'CONTRADICTED', 'INDETERMINATE', 'NOT_OBSERVED']);
+  if (relevanceStatus !== 'RELEVANT' || !supportStatus || supportStatus === 'NOT_ASSESSED' || !supportedStates.has(supportStatus)) return { status: 'INDETERMINATE', reasons: ['source relevance or proposition support was not established'], evidence_references: [retrieval.observation_id, ...evidenceReferences] };
+  return { status: supportStatus, reasons: [], evidence_references: [retrieval.observation_id, ...evidenceReferences] };
+}
+
+/** Derive prevalence over successful/evaluable executions only, retaining exclusions. */
+export function deriveRepresentationPrevalence(observations, { predicatePath = 'data.representation.brand_mentioned', expected = true, derivationId = 'REPRESENTATION-PREVALENCE', derivationVersion = 1 } = {}) {
+  if (!Array.isArray(observations) || !observations.length) throw new TypeError('observations are required');
+  const valid = observations.filter((item) => verifyExternalObservation(item).valid);
+  const evaluable = valid.filter((item) => item.data?.response?.status === 'succeeded');
+  const excluded = observations.filter((item) => !verifyExternalObservation(item).valid || item.data?.response?.status !== 'succeeded');
+  const valueAt = (item) => predicatePath.split('.').reduce((v, key) => v == null ? undefined : v[key], item);
+  const numerator = evaluable.filter((item) => valueAt(item) === expected).length;
+  return createDerivation({
+    derivation_id: derivationId,
+    derivation_version: derivationVersion,
+    operation: 'representation_prevalence',
+    input_observation_references: observations.map((item) => item.observation_id),
+    predicate: { path: predicatePath, operator: 'equals', value: expected },
+    result: {
+      numerator,
+      denominator: evaluable.length,
+      rate: evaluable.length ? numerator / evaluable.length : null,
+      evaluable_observation_references: evaluable.map((item) => item.observation_id),
+      excluded_observation_references: excluded.map((item) => item.observation_id),
+      exclusions: excluded.map((item) => ({ observation_reference: item.observation_id, reason: verifyExternalObservation(item).valid ? (item.data?.response?.status || 'not_evaluable') : 'integrity_unverifiable' })),
+      population_scope: 'successful_representation_executions_in_supplied_observations',
+    },
+    implementation: { id: 'citable-representation-prevalence', version: '1.0.0' },
+  });
+}
+
+export function citationsForExecution(citations, executionId) { return (citations || []).filter((item) => item.data?.execution_reference === executionId); }
+export function citationsForProposition(citations, propositionId) { return (citations || []).filter((item) => item.data?.proposition?.proposition_id === propositionId); }
+export function sourceForCitation(retrievals, citationId) { return (retrievals || []).find((item) => item.data?.citation_reference === citationId) || null; }
+export function evidenceForProposition(retrievals, propositionId, citations = []) {
+  const citationIds = new Set(citationsForProposition(citations, propositionId).map((item) => item.observation_id));
+  return (retrievals || []).filter((item) => citationIds.has(item.data?.citation_reference));
+}
+
+export { verifyClaim };