@nebulacomponents/citable 1.19.0 → 1.21.0

package/src/evidence/downstream.js

@@ -0,0 +1,110 @@
+/**
+ * Shared semantics for consumers that summarize or act on an evidence package.
+ * A consumer may describe the evaluated subset, but may not widen it to the
+ * requested scope when collection was incomplete or empty.
+ */
+const DETERMINATION_STATUSES = new Set(['supported', 'qualified', 'indeterminate', 'not_applicable']);
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+function populations(coverage) {
+  return coverage?.populations && typeof coverage.populations === 'object'
+    ? coverage.populations : {};
+}
+
+function contractStatus(coverage) {
+  if (!coverage || typeof coverage !== 'object') return { valid: false, errors: ['coverage artifact unavailable'] };
+  const result = validateAgainst('audit-coverage.schema.json', coverage);
+  return { valid: result.valid, errors: result.errors || [] };
+}
+
+export function coverageDenominator(coverage) {
+  const value = populations(coverage).evaluated;
+  return Number.isInteger(value) && value > 0 ? value : 0;
+}
+
+export function completeLocalCoverage(pages, baseUrl = 'https://example.test') {
+  const origin = new URL(baseUrl).origin;
+  const resources = pages.map((page, index) => ({
+    resource_id: `LOCAL-${index + 1}`,
+    normalized_url: page.url || `${origin}/page-${index + 1}`,
+    original_urls: [page.url || `${origin}/page-${index + 1}`],
+    state: 'evaluated',
+    evaluation: {},
+  }));
+  const n = resources.length;
+  return {
+    schema_version: 1,
+    normalization_version: 'url-identity-v1',
+    requested_scope: { start_url: `${origin}/`, origin, max_pages: 500, time_budget_seconds: 1800 },
+    discovery: { status: 'complete', methods: ['built_output'], limitations: [] },
+    populations: { discovered: n, eligible: n, excluded: 0, attempted: n, retrieved: n, valid_resource: n, evaluated: n, valid_but_unevaluated: 0, failed: 0, indeterminate: 0, unvisited: 0 },
+    resources,
+    stop_reason: 'frontier_exhausted',
+    coverage_status: 'complete',
+    reconciliation: { valid: true, errors: [] },
+    limitations: [],
+  };
+}
+
+export function downstreamStatus(coverage) {
+  if (!coverage) return 'indeterminate';
+  const contract = contractStatus(coverage);
+  const denominator = coverageDenominator(coverage);
+  const p = populations(coverage);
+  const completePopulation = p.failed === 0 && p.indeterminate === 0 && p.unvisited === 0 && p.valid_but_unevaluated === 0;
+  if (coverage.coverage_status === 'complete' && denominator > 0 && completePopulation && contract.valid && coverage.reconciliation?.valid === true) return 'supported';
+  if (coverage.coverage_status === 'truncated' && denominator > 0
+    && contract.valid && coverage.reconciliation?.valid === true) return 'qualified';
+  return 'indeterminate';
+}
+
+export function coverageLimitations(coverage) {
+  if (!coverage) return ['coverage artifact unavailable; scope is not established'];
+  const p = populations(coverage);
+  const limitations = Array.isArray(coverage.limitations) ? [...coverage.limitations] : [];
+  const contract = contractStatus(coverage);
+  if (!contract.valid) limitations.push('coverage artifact does not satisfy the coverage contract');
+  if (coverage.coverage_status !== 'complete') {
+    limitations.push(`coverage is ${coverage.coverage_status || 'unknown'}; conclusions are limited to evaluated resources`);
+  }
+  for (const key of ['failed', 'indeterminate', 'unvisited', 'valid_but_unevaluated']) {
+    if (Number.isInteger(p[key]) && p[key] > 0) limitations.push(`${p[key]} ${key} resource(s) omitted from determinations`);
+  }
+  return [...new Set(limitations)];
+}
+
+export function downstreamEnvelope(coverage, extra = {}) {
+  const p = populations(coverage);
+  const denominator = coverageDenominator(coverage);
+  const status = downstreamStatus(coverage);
+  if (!DETERMINATION_STATUSES.has(status)) throw new Error(`invalid downstream determination status: ${status}`);
+  return {
+    coverage_status: coverage?.coverage_status || 'indeterminate',
+    determination_status: status,
+    evidence_scope: {
+      requirement: 'evaluated_subset',
+      satisfaction: status,
+      coverage_ref: coverage ? 'coverage.json' : null,
+      resource_ids: Array.isArray(coverage?.resources)
+        ? coverage.resources.map((resource) => resource.resource_id).filter(Boolean)
+        : [],
+      population: denominator > 0 ? 'evaluated_subset' : 'none_observed',
+      evaluated: denominator,
+      eligible: Number.isInteger(p.eligible) ? p.eligible : null,
+      excluded: Number.isInteger(p.excluded) ? p.excluded : null,
+      failed: Number.isInteger(p.failed) ? p.failed : null,
+      indeterminate: Number.isInteger(p.indeterminate) ? p.indeterminate : null,
+      unvisited: Number.isInteger(p.unvisited) ? p.unvisited : null,
+      denominator,
+    },
+    limitations: coverageLimitations(coverage),
+    ...extra,
+  };
+}
+
+/** Return null for empty evidence; never divide by a convenient zero. */
+export function scoreFromCoverage(numerator, coverage, { scale = 100 } = {}) {
+  const denominator = coverageDenominator(coverage);
+  if (!Number.isFinite(numerator) || denominator === 0) return null;
+  return Math.round((numerator / denominator) * scale);
+}

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/evidence/hashes.js

@@ -0,0 +1,109 @@
+import { sha256 } from '../shared/io.js';
+
+export const EVIDENCE_HASH_SCHEMA_VERSION = 'evidence-hashes-v1';
+
+/**
+ * Canonical JSON used for evidence representations. Object key order is not
+ * evidence; array order is preserved because it can be meaningful (for
+ * example, JSON-LD graph order and an evaluator's finding order).
+ */
+export function canonicalEvidenceJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalEvidenceJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalEvidenceJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function bytes(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  return Buffer.from(String(value ?? ''), 'utf8');
+}
+
+function hashBytes(value) {
+  return sha256(bytes(value));
+}
+
+function hashCanonical(value) {
+  return sha256(canonicalEvidenceJson(value));
+}
+
+/** Normalize only extraction whitespace; do not remove content or metadata. */
+export function normalizeExtractedText(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Build named hashes for representations that are actually available.
+ * Null means that representation was not observed; it is never synthesized
+ * from another layer.
+ */
+export function createEvidenceHashes({
+  responseBody,
+  extractedText,
+  structuredData,
+  renderedDom,
+  evidence,
+  artifact,
+} = {}) {
+  return {
+    hash_schema_version: EVIDENCE_HASH_SCHEMA_VERSION,
+    response_body_hash: responseBody == null ? null : hashBytes(responseBody),
+    rendered_dom_hash: renderedDom == null ? null : hashBytes(renderedDom),
+    extracted_text_hash: extractedText == null ? null : hashBytes(normalizeExtractedText(extractedText)),
+    structured_data_hash: structuredData == null ? null : hashCanonical(structuredData),
+    evidence_hash: evidence == null ? null : hashCanonical(evidence),
+    artifact_hash: artifact == null ? null : hashCanonical(artifact),
+  };
+}
+
+/** Explicit legacy meaning for snapshots and connector payloads during migration. */
+export const LEGACY_CONTENT_HASH_SEMANTICS = 'extracted_text_v1';
+
+/**
+ * Canonical shape of the persisted pages/index.json record. The artifact hash
+ * is intentionally excluded so the hash does not contain itself; verification
+ * recomputes this exact record shape and compares it with the stored claim.
+ */
+export function pageArtifactRecord(page) {
+  return {
+    url: page.url,
+    status: page.status,
+    title: page.title,
+    canonicals: page.canonicals,
+    noindex: page.noindex,
+    wordCount: page.wordCount,
+    sourceFile: page.sourceFile,
+    requested_url: page.requestedUrl ?? null,
+    effective_url: page.url,
+    declared_canonical_url: page.canonicals?.[0] ?? null,
+    resource_id: page.urlIdentity?.resource_id ?? null,
+    url_identity: page.urlIdentity ?? null,
+    hash_schema_version: page.hash_schema_version ?? null,
+    response_body_hash: page.response_body_hash ?? null,
+    rendered_dom_hash: page.rendered_dom_hash ?? null,
+    extracted_text_hash: page.extracted_text_hash ?? null,
+    structured_data_hash: page.structured_data_hash ?? null,
+    evidence_hash: page.evidence_hash ?? null,
+    contentHash: page.extracted_text_hash ?? null,
+    hash_semantics: LEGACY_CONTENT_HASH_SEMANTICS,
+  };
+}
+
+export function hashPageArtifact(page) {
+  return hashCanonical(pageArtifactRecord(page));
+}
+
+/** Bind a determination/finding to the representation its hash actually covers. */
+export function evidenceIdentity(hashes, representation) {
+  const field = `${representation}_hash`;
+  const hash = hashes?.[field];
+  if (!['response_body', 'rendered_dom', 'extracted_text', 'structured_data', 'evidence', 'artifact'].includes(representation)) {
+    throw new TypeError(`unknown evidence representation: ${representation}`);
+  }
+  if (typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash)) {
+    throw new Error(`evidence representation is unavailable: ${representation}`);
+  }
+  return { hash_schema_version: hashes.hash_schema_version ?? EVIDENCE_HASH_SCHEMA_VERSION, representation, hash };
+}

package/src/evidence/run.js

@@ -23,6 +23,26 @@ function gitInfo(root) {
   }
 }
 
+function assertSafeArtifactPath(runDir, relativePath) {
+  if (typeof relativePath !== 'string' || !relativePath || path.isAbsolute(relativePath) || relativePath.includes('\\')) {
+    throw new Error(`unsafe artifact path: ${relativePath}`);
+  }
+  const parts = relativePath.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..')) throw new Error(`unsafe artifact path: ${relativePath}`);
+  let current = runDir;
+  for (const part of parts) {
+    current = path.join(current, part);
+    if (!fs.existsSync(current)) continue;
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) throw new Error(`artifact path contains symbolic link: ${relativePath}`);
+  }
+}
+
+function fsyncPath(file) {
+  const handle = fs.openSync(file, 'r');
+  try { fs.fsyncSync(handle); } finally { fs.closeSync(handle); }
+}
+
 /** Create a run evidence package under <root>/.citable/runs/<run-id>/. */
 export function createRun(root, { command, argv = [], target, locale = process.env.LANG || 'en', jurisdiction = null, configHash = null }) {
   const runId = newRunId(command);
@@ -30,6 +50,7 @@ export function createRun(root, { command, argv = [], target, locale = process.e
   fs.mkdirSync(dir, { recursive: true });
   const git = gitInfo(root);
   const manifest = {
+    schema_version: 2,
     run_id: runId,
     command,
     argv,
@@ -50,6 +71,9 @@ export function createRun(root, { command, argv = [], target, locale = process.e
     errors: [],
     warnings: [],
     status: 'incomplete',
+    execution_status: 'completed',
+    coverage_status: 'not_applicable',
+    determination_status: 'not_applicable',
   };
   return {
     runId,
@@ -59,6 +83,7 @@ export function createRun(root, { command, argv = [], target, locale = process.e
       manifest.input_hashes[name] = sha256(typeof content === 'string' ? content : JSON.stringify(content));
     },
     writeArtifact(relPath, data) {
+      assertSafeArtifactPath(dir, relPath);
       const file = path.join(dir, relPath);
       fs.mkdirSync(path.dirname(file), { recursive: true });
       if (typeof data === 'string' || Buffer.isBuffer(data)) fs.writeFileSync(file, data);
@@ -70,18 +95,53 @@ export function createRun(root, { command, argv = [], target, locale = process.e
       manifest.status = status;
       const { valid, errors } = validateAgainst('run.schema.json', manifest);
       if (!valid) throw new Error(`run manifest invalid: ${errors.join('; ')}`);
-      writeJson(path.join(dir, 'manifest.json'), manifest);
+      const stage = `${dir}.sealing-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+      fs.rmSync(stage, { recursive: true, force: true });
+      fs.cpSync(dir, stage, { recursive: true, dereference: false, errorOnExist: true });
+      writeJson(path.join(stage, 'manifest.json'), manifest);
+      const summaryFile = path.join(stage, 'summary.json');
+      if (fs.existsSync(summaryFile)) {
+        // Keep the persisted ordering contract deterministic even on filesystems
+        // with coarse timestamp resolution or delayed copy metadata updates.
+        const now = new Date(Date.now() + 1000);
+        fs.utimesSync(summaryFile, now, now);
+      }
       // checksums over every artifact in the package
-      const checksums = {};
+      const checksumEntries = [];
       const walk = (d) => {
-        for (const name of fs.readdirSync(d)) {
-          const p = path.join(d, name);
-          if (fs.statSync(p).isDirectory()) walk(p);
-          else if (name !== 'checksums.json') checksums[path.relative(dir, p)] = sha256File(p);
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+          const p = path.join(d, entry.name);
+          if (entry.isSymbolicLink()) throw new Error(`staging package contains symbolic link: ${path.relative(stage, p)}`);
+          if (entry.isDirectory()) walk(p);
+          else if (entry.isFile() && entry.name !== 'checksums.json') checksumEntries.push([path.relative(stage, p).split(path.sep).join('/'), sha256File(p)]);
+          else if (!entry.isFile()) throw new Error(`staging package contains unsupported entry: ${path.relative(stage, p)}`);
+        }
+      };
+      walk(stage);
+      const checksums = Object.fromEntries(checksumEntries.sort(([a], [b]) => a.localeCompare(b)));
+      writeJson(path.join(stage, 'checksums.json'), checksums);
+      const fsyncTree = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+          const file = path.join(directory, entry.name);
+          if (entry.isSymbolicLink()) throw new Error(`staging package contains symbolic link: ${path.relative(stage, file)}`);
+          if (entry.isDirectory()) fsyncTree(file);
+          else if (entry.isFile()) fsyncPath(file);
         }
+        fsyncPath(directory);
       };
-      walk(dir);
-      writeJson(path.join(dir, 'checksums.json'), checksums);
+      fsyncTree(stage);
+      const parent = path.dirname(dir);
+      const displaced = `${dir}.partial-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+      fs.renameSync(dir, displaced);
+      try {
+        fs.renameSync(stage, dir);
+        fs.rmSync(displaced, { recursive: true, force: true });
+        fsyncPath(parent);
+      } catch (error) {
+        if (!fs.existsSync(dir) && fs.existsSync(displaced)) fs.renameSync(displaced, dir);
+        fs.rmSync(stage, { recursive: true, force: true });
+        throw error;
+      }
       return dir;
     },
   };

package/src/extractor/page.js

@@ -1,10 +1,11 @@
 import { parse } from 'node-html-parser';
+import { createEvidenceHashes, hashPageArtifact } from '../evidence/hashes.js';
 
 /**
  * Extract a PageModel from raw HTML plus transport metadata.
  * Everything downstream (detectors, inspect, schema) consumes this model.
  */
-export function extractPage({ url, html, status = 200, headers = {}, sourceFile = null, redirectChain = [] }) {
+export function extractPage({ url, html, responseBody = null, status = 200, headers = {}, sourceFile = null, redirectChain = [], renderedDom = null }) {
   const root = parse(html, { comment: true });
   const head = root.querySelector('head');
 
@@ -282,7 +283,7 @@ export function extractPage({ url, html, status = 200, headers = {}, sourceFile
   };
   walkDom(root, 1);
 
-  return {
+  const page = {
     url,
     sourceFile,
     status,
@@ -323,4 +324,30 @@ export function extractPage({ url, html, status = 200, headers = {}, sourceFile
     domNodeCount,
     maxDomDepth,
   };
+
+  // Keep representation identity explicit. These hashes deliberately do not
+  // share a generic `contentHash`: raw response bytes, extracted text,
+  // structured data, evaluator evidence, and the persisted page artifact are
+  // different claims and may change independently.
+  const hashes = createEvidenceHashes({
+    responseBody: responseBody ?? html,
+    renderedDom,
+    extractedText: text,
+    structuredData: jsonLd.length
+      ? jsonLd.map(({ parsed, blocks, parseError }) => ({ parsed, blocks, parseError }))
+      : null,
+    evidence: {
+      extracted_text: text,
+      headings,
+      paragraphs,
+      structured_data: jsonLd.map(({ parsed, blocks, parseError }) => ({ parsed, blocks, parseError })),
+    },
+    // This is replaced after URL/resource metadata is attached; keeping the
+    // field null here prevents a pre-persistence model from being presented as
+    // the persisted artifact identity.
+    artifact: null,
+  });
+  const withHashes = { ...page, ...hashes };
+  withHashes.artifact_hash = hashPageArtifact(withHashes);
+  return withHashes;
 }