@nebulacomponents/citable 1.12.0 → 1.13.0

package/scripts/release-governance.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import {
+  createDeploymentReceipt,
+  generateReleaseManifest,
+  initializeReleaseState,
+  transitionRelease,
+  validateReleaseManifest,
+  verifyManifestIntegrity,
+  verifyRepositoryBinding,
+} from '../src/release/governance.js';
+import { writeJson } from '../src/shared/io.js';
+
+function read(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function generatedFiles(dir) {
+  const files = {};
+  for (const [name, key] of [['resource-data.json', 'release/resource-data.json'], ['llms.txt', 'release/llms.txt']]) {
+    const file = path.join(dir, name);
+    if (fs.existsSync(file)) files[key] = fs.readFileSync(file, 'utf8');
+  }
+  return files;
+}
+
+function requireArg(value, usage) {
+  if (!value) throw new Error(usage);
+  return value;
+}
+
+export function runReleaseGovernance(argv, root = process.cwd()) {
+  const [command, ...args] = argv;
+  if (command === 'manifest') {
+    const outputDir = path.resolve(requireArg(args[0], 'manifest requires <output-dir>'));
+    const commit = args[1];
+    const boundCommit = commit || execFileCommit(root);
+    const binding = verifyRepositoryBinding(root, boundCommit);
+    if (!binding.ok) throw new Error(`release source binding failed: ${binding.failures.join('; ')}`);
+    const result = generateReleaseManifest(root, { outputDir, commit: boundCommit });
+    return { command, output: path.join(outputDir, 'release-manifest.json'), manifest: result.manifest };
+  }
+  if (command === 'validate') {
+    const manifestFile = path.resolve(requireArg(args[0], 'validate requires <manifest-file>'));
+    const projectionDir = path.resolve(args[1] || path.dirname(manifestFile));
+    const manifest = read(manifestFile);
+    const binding = verifyRepositoryBinding(root, manifest.commit);
+    if (!binding.ok) throw new Error(`release source binding failed: ${binding.failures.join('; ')}`);
+    const result = validateReleaseManifest(root, manifest, generatedFiles(projectionDir));
+    if (!result.ok) throw new Error(`phase-one release validation failed: ${result.failures.join('; ')}`);
+    return { command, ok: true };
+  }
+  if (command === 'state-init') {
+    const manifestFile = path.resolve(requireArg(args[0], 'state-init requires <manifest-file> <output-file> <actor>'));
+    const outputFile = path.resolve(requireArg(args[1], 'state-init requires <manifest-file> <output-file> <actor>'));
+    const actor = requireArg(args[2], 'state-init requires <manifest-file> <output-file> <actor>');
+    const manifest = read(manifestFile);
+    const integrity = verifyManifestIntegrity(manifest);
+    if (!integrity.ok) throw new Error(`manifest integrity failed: ${integrity.failures.join('; ')}`);
+    const state = initializeReleaseState(manifest, { actor, maxDwellHours: Number(process.env.CITABLE_RELEASE_DWELL_HOURS || 24) });
+    writeJson(outputFile, state);
+    return { command, output: outputFile, state };
+  }
+  if (command === 'state-publish') {
+    const manifestFile = path.resolve(requireArg(args[0], 'state-publish requires <manifest-file> <state-file> <actor>'));
+    const stateFile = path.resolve(requireArg(args[1], 'state-publish requires <manifest-file> <state-file> <actor>'));
+    const actor = requireArg(args[2], 'state-publish requires <manifest-file> <state-file> <actor>');
+    const manifest = read(manifestFile);
+    const binding = verifyRepositoryBinding(root, manifest.commit);
+    if (!binding.ok) throw new Error(`release source binding failed: ${binding.failures.join('; ')}`);
+    const phaseOne = validateReleaseManifest(root, manifest, generatedFiles(path.dirname(manifestFile)));
+    if (!phaseOne.ok) throw new Error(`phase-one release validation failed: ${phaseOne.failures.join('; ')}`);
+    const state = transitionRelease(read(stateFile), 'published_unfinalized', { actor, reason: 'Immutable npm package and release references published.', phaseOne: { ok: true, manifest_hash: manifest.manifest_hash }, evidenceRefs: [manifest.manifest_hash, `https://www.npmjs.com/package/@nebulacomponents/citable/v/${manifest.version}`] });
+    writeJson(stateFile, state);
+    return { command, output: stateFile, state };
+  }
+  if (command === 'receipt') {
+    const manifestFile = path.resolve(requireArg(args[0], 'receipt requires <manifest-file> <observation-file> <output-file>'));
+    const observationFile = path.resolve(requireArg(args[1], 'receipt requires <manifest-file> <observation-file> <output-file>'));
+    const outputFile = path.resolve(requireArg(args[2], 'receipt requires <manifest-file> <observation-file> <output-file>'));
+    const receipt = createDeploymentReceipt(read(manifestFile), read(observationFile));
+    writeJson(outputFile, receipt);
+    return { command, output: outputFile, receipt };
+  }
+  if (command === 'state-finalize') {
+    const manifestFile = path.resolve(requireArg(args[0], 'state-finalize requires <manifest-file> <state-file> <actor> <receipt...>'));
+    const stateFile = path.resolve(requireArg(args[1], 'state-finalize requires <manifest-file> <state-file> <actor> <receipt...>'));
+    const actor = requireArg(args[2], 'state-finalize requires <manifest-file> <state-file> <actor> <receipt...>');
+    const receiptFiles = args.slice(3);
+    if (!receiptFiles.length) throw new Error('state-finalize requires at least one receipt');
+    const manifest = read(manifestFile);
+    const receipts = receiptFiles.map((file) => read(path.resolve(file)));
+    const state = transitionRelease(read(stateFile), 'finalized', { actor, reason: 'All required publisher-controlled surfaces verified.', manifest, receipts, evidenceRefs: receipts.map((item) => item.receipt_hash) });
+    writeJson(stateFile, state);
+    return { command, output: stateFile, state };
+  }
+  if (command === 'state-resolve') {
+    const stateFile = path.resolve(requireArg(args[0], 'state-resolve requires <state-file> <withdrawn|superseded> <actor> <reason> [superseding-release-id]'));
+    const to = requireArg(args[1], 'state-resolve requires a terminal state');
+    const actor = requireArg(args[2], 'state-resolve requires an actor');
+    const reason = requireArg(args[3], 'state-resolve requires a reason');
+    const state = transitionRelease(read(stateFile), to, { actor, reason, supersedingReleaseId: args[4] || null });
+    writeJson(stateFile, state);
+    return { command, output: stateFile, state };
+  }
+  throw new Error('usage: release-governance <manifest|validate|state-init|state-publish|receipt|state-finalize|state-resolve> ...');
+}
+
+function execFileCommit(root) {
+  return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8' }).trim();
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = runReleaseGovernance(process.argv.slice(2));
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`release-governance: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

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.12.0
+version: 1.13.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -97,6 +97,7 @@ citable action-plan [run-id]          # ordered actions, blockers, semantic gate
 citable observe <mode> [options]      # render/index/citation/log/passage/consensus/performance evidence
 citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
 citable observe render --target <url> [--interactions] [--resume-run <run-id>]
+citable observe render --input <browser-evidence-plan.json>
 citable observe performance --target <url> --lighthouse [--repeat 1..5]
 citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
 citable monitor [runA runB]           # observation regression alerts
@@ -120,6 +121,14 @@ citable reviews evaluate
 citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
 citable project github <run-id>
 citable observe media --input <manifest.json> [--ocr]
+citable observe representation --input <release-manifest.json> --target <controlled-url>
+citable corpus evaluate --input <acceptance-corpus.json>
+citable corpus publish --input <acceptance-corpus.json> --output <public-corpus.json>
+citable corpus receipt --run <run-id> [--input <execution-context.json>]
+citable corpus compare-receipts <receipt-a.json> <receipt-b.json>
+citable artifacts export <run-id> --output <directory>
+citable artifacts verify --input <directory>
+citable artifacts import --input <directory>
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -164,6 +173,8 @@ operator data or future adapters.
 Use `commands/observe-and-act.md` for collector prerequisites, evidence labels,
 the controlled citation adapter protocol, remediation refusal conditions, and
 monitoring interpretation.
+Use `commands/field-validation.md` for acceptance-corpus authorization,
+sanitization, publication refusal, reproducibility, and evidence boundaries.
 
 ## Command workflows
 

package/skill/commands/README.md

@@ -34,8 +34,9 @@ intent, not executability, so statuses are strict:
 | /citable ingest, map-site, map-queries, map-prompts, map-entities, map-evidence | specified (ingest.md) |
 | /citable optimize-page | specified (optimize-page.md) — requires source-to-render mapping, claim-preserving rewrites, build execution, rollback; none of that is proven yet |
 | /citable create-page, answer-block, architect, interlink, consolidate, metadata | specified (page-work.md) |
-| /citable validate-render | partially implemented by `observe render`; desktop/mobile/JavaScript-disabled profiles and bounded interaction exploration are implemented, while cross-browser and application-specific journeys remain |
+| /citable validate-render | partially implemented by `observe render`; fixed Chromium profiles and schema-validated Chromium/Firefox/WebKit journeys are implemented, while reviewed semantic-impact detectors and reusable application-specific journey libraries remain |
 | /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by metric/observation imports, objective evaluation, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
+| `citable artifacts export/verify/import` | implemented — portable, versioned, checksum-bound run interchange without hosted-service authority |
 
 Shared refusal conditions (all commands): any action that would fabricate
 facts, citations, evidence, authorship, reviews, corroboration, or hidden

package/skill/commands/artifact-interchange.md

@@ -0,0 +1,28 @@
+# Portable artifact interchange
+
+Use artifact interchange to move one sealed Citable run between local or
+external workspaces without changing its canonical bytes.
+
+```sh
+citable artifacts export <run-id> --output <directory>
+citable artifacts verify --input <directory>
+citable artifacts import --input <directory>
+```
+
+An export contains the original run package plus
+`citable-artifact.json`. The versioned envelope binds the run identity,
+exporter identity, source-run versions, manifest and checksum hashes, exact
+artifact inventory, byte sizes, and a canonical package hash. Verification rejects missing,
+additional, modified, unsafe, or symbolic-link entries. Import verifies into a
+temporary directory before atomically creating `.citable/runs/<run-id>`.
+
+Import never rewrites the run manifest, checksums, or artifacts. An identical
+existing run is `already_present`; a different package with the same run ID is
+a collision and fails closed. The interchange envelope is transport metadata
+and is not copied into the canonical run package.
+
+Checksums prove preservation after export. They do not prove that the source
+was authentic, that external observations were representative or complete, or
+that an intervention caused an outcome. Hosted tenancy, authentication,
+storage, retention, billing, scheduling, and dashboards are outside this
+contract.

package/skill/commands/field-validation.md

@@ -0,0 +1,71 @@
+# Field validation corpus
+
+Use this workflow to assemble, evaluate, and publish an acceptance corpus. A
+fixture-valid corpus is not field evidence. Do not describe a corpus as real,
+representative, accurate, or public until the corresponding records and reviews
+exist.
+
+## Preconditions
+
+For every property, record:
+
+- architecture and property class;
+- owner authorization for collection, retention, review, and the intended
+  publication level;
+- collection methods, authority labels, timestamps, and limitations;
+- unavailable evidence, intentional incompleteness, and contradictions;
+- publication approval, retention, and the exact artifact-reference allowlist;
+- human sanitization review covering personal data, credentials, and source
+  identifiers.
+
+Every execution must reference raw artifacts, deterministic and heuristic
+findings, reviewer assignments, disagreements, exceptions, interventions,
+verification, and its reproducibility receipt where available. Empty reference
+arrays are valid only where that class of evidence did not occur.
+
+## Evaluate
+
+```sh
+citable corpus evaluate --input acceptance-corpus.json
+```
+
+Evaluation validates the v2 contract and writes `accuracy-metrics.json` plus a
+human-readable `accuracy-metrics.md` projection from the same hash-bound data.
+Every reported metric discloses its numerator, denominator, population,
+exclusions, and confidence limits. Sample and census designs remain distinct,
+and detector versions are reported as separate cohorts. Evaluation does not
+authorize publication. Unknown false negatives remain unknown; discovered
+false-negative rates apply only to adjudicated expected detections in the
+disclosed population.
+
+## Publish
+
+```sh
+citable corpus publish \
+  --input acceptance-corpus.json \
+  --output public-corpus.json
+```
+
+Publication fails closed when any property is private or aggregate-only, owner
+authority is expired or incomplete, sanitization review is incomplete, an
+artifact reference is unsafe or outside the allowlist, sensitive patterns are
+detected, or the output already exists. It emits the public corpus, a hash-bound
+publisher-controlled receipt, and an immutable local evidence package.
+
+Automated checks supplement but do not replace human sanitization review. The
+receipt is owner-authorized publication evidence, not independent attestation.
+Never publish production credentials, customer data, private property artifacts,
+or evidence outside the exact approved scope.
+
+## Reproducibility
+
+Create one receipt per sealed acceptance run, then compare repeated envelopes:
+
+```sh
+citable corpus receipt --run <run-id> --input execution-context.json
+citable corpus compare-receipts <receipt-a.json> <receipt-b.json>
+```
+
+Treat fingerprint equality as bounded equality of declared inputs, methods,
+tools, external-system versions, and artifacts. It does not establish causation
+or performance on untested properties.

package/skill/commands/observe-and-act.md

@@ -14,6 +14,11 @@ failure_behaviour: unavailable dependency, credential, source run, reviewer, exa
   disclosure, inactive-tab, and load-more-like controls; it does not prove an
   application-specific journey. `--resume-run` reuses only successful profile
   observations from the named immutable run and recollects failed/absent ones.
+  `observe render --input <browser-evidence-plan.json>` executes an
+  explicit Chromium, Firefox, or WebKit profile matrix. Each plan records the
+  browser version, device, JavaScript, locale, consent, authentication state,
+  and ordered interaction steps. Fill/select values are referenced by
+  environment-variable name and are never written to the plan or artifacts.
 - `observe index --input <JSON>` imports owner exports. With `--target`,
   `--site-url`, and `GSC_ACCESS_TOKEN`, it calls Google URL Inspection, which
   reports the indexed version rather than performing a live indexability test.

package/skill/references/aeo-geo-validation.md

@@ -9,7 +9,7 @@ not a prediction of citation or recommendation. Report every row as
 | State | Current evidence boundary |
 | --- | --- |
 | Retrieval eligibility | Static policy plus captured synthetic HTTP response; crawler identity remains simulated unless verified logs/IP evidence are supplied |
-| Source extraction and support suitability | Initial HTML plus registries/detectors/rubrics; optional Chromium profiles can establish bounded raw/desktop/mobile/JavaScript-disabled parity, while cross-browser and application-specific journeys remain unproven |
+| Source extraction and support suitability | Initial HTML plus registries/detectors/rubrics; optional fixed Chromium profiles and explicit Chromium/Firefox/WebKit journey plans establish bounded artifact-level parity, while semantic impact remains unproven |
 | Observed citation behavior | Operator-supplied prompt-result observations only; report cohort size and property citation presence, never infer from readiness |
 
 ## AEO checks

package/skill/references/capability-boundaries.md

@@ -10,6 +10,7 @@ Use the narrowest supported state. Never promote evidence across rows.
 | Observed in production logs | Imported evidence | Timestamped `observe logs` artifact with URL, status, bytes, latency, cache result, UA, and verification result |
 | Indexed | Google API or imported evidence | `observe index`; Google inspection covers the indexed version, other engines require owner exports |
 | Rendered profile observed | Optional local browser evidence | Successful profile-specific Chromium DOM, text, screenshot, failed requests, interactions, viewport, and configuration; failed profiles remain independent |
+| Browser journey observed | Schema-validated local browser plan | Engine/version, device, JavaScript, locale, consent, authentication declaration, steps, DOM, text, accessibility snapshot, screenshots, and failures remain separate; differences do not establish semantic or citation impact |
 | Render parity compared | Bounded local comparison | Raw/desktop and mobile/desktop word ratios from the same run or explicitly resumed immutable profiles; not semantic equivalence |
 | Returned by retrieval | Operator supplied | Provider observation containing retrieved source URL |
 | Cited | Import or disclosed adapter | Complete `observe citations` answer with citation URL and product/adapter mode |

package/src/acceptance/reproducibility.js

@@ -0,0 +1,180 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson } from '../release/governance.js';
+import { nowIso, readJson, sha256, sha256File, writeJson } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const INCLUDED_FIELDS = [
+  'property.target', 'property.source_commit', 'property.content_hashes',
+  'detectors', 'configuration.hash', 'observation_method', 'toolchain',
+  'external_systems', 'canonical_artifacts', 'execution.status',
+  'execution.unavailable_observations', 'execution.errors',
+];
+
+const EXCLUDED_FIELDS = [
+  'run_id', 'execution.started_at', 'execution.receipt_created_at',
+  'execution.locale', 'execution.region', 'property.working_tree_state',
+  'host identity', 'filesystem paths', 'runtime duration', 'memory consumption',
+];
+
+function sortedObject(value = {}) {
+  return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function normalizedArguments(argv = []) {
+  const pathFlags = new Set(['--target', '--input', '--resume-run']);
+  const normalized = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = String(argv[index]);
+    normalized.push(value);
+    if (pathFlags.has(value) && index + 1 < argv.length) {
+      normalized.push('<excluded-path-or-run>');
+      index += 1;
+    } else if (path.isAbsolute(value)) {
+      normalized[normalized.length - 1] = '<excluded-path>';
+    }
+  }
+  return normalized;
+}
+
+function verifyRunPackage(runDir, manifest) {
+  const manifestCheck = validateAgainst('run.schema.json', manifest);
+  if (!manifestCheck.valid) throw new Error(`run manifest violates contract: ${manifestCheck.errors.join('; ')}`);
+  const checksumsFile = path.join(runDir, 'checksums.json');
+  if (!fs.existsSync(checksumsFile)) throw new Error(`run ${manifest.run_id} has no checksums.json`);
+  const checksums = readJson(checksumsFile);
+  if (!checksums || Array.isArray(checksums) || typeof checksums !== 'object') throw new Error('run checksums must be an object');
+  const failures = [];
+  for (const [relative, expected] of Object.entries(checksums)) {
+    const file = path.resolve(runDir, relative);
+    if (path.isAbsolute(relative) || (!file.startsWith(`${path.resolve(runDir)}${path.sep}`))) failures.push(`${relative} escapes the run package`);
+    else if (!/^[a-f0-9]{64}$/.test(expected)) failures.push(`${relative} has an invalid checksum`);
+    else if (!fs.existsSync(file)) failures.push(`${relative} is missing`);
+    else if (sha256File(file) !== expected) failures.push(`${relative} checksum differs`);
+  }
+  if (failures.length) throw new Error(`run package integrity failed: ${failures.join('; ')}`);
+  return checksums;
+}
+
+function fingerprintPayload(receipt) {
+  return {
+    property: { target: receipt.property.target, source_commit: receipt.property.source_commit, content_hashes: receipt.property.content_hashes },
+    detectors: receipt.detectors,
+    configuration: receipt.configuration,
+    observation_method: receipt.observation_method,
+    toolchain: receipt.toolchain,
+    external_systems: receipt.external_systems,
+    canonical_artifacts: receipt.canonical_artifacts,
+    execution: { status: receipt.execution.status, unavailable_observations: receipt.execution.unavailable_observations, errors: receipt.execution.errors },
+  };
+}
+
+export function createAcceptanceReceipt(root, { runId, context = {}, createdAt = nowIso() }) {
+  if (!runId) throw new Error('corpus receipt requires --run <run-id>');
+  const contextCheck = validateAgainst('acceptance-run-context.schema.json', context);
+  if (!contextCheck.valid) throw new Error(`acceptance context violates contract: ${contextCheck.errors.join('; ')}`);
+  const runDir = path.join(root, '.citable', 'runs', runId);
+  const manifestFile = path.join(runDir, 'manifest.json');
+  if (!fs.existsSync(manifestFile)) throw new Error(`run ${runId} not found`);
+  const manifest = readJson(manifestFile);
+  if (manifest.run_id !== runId) throw new Error(`run manifest id ${manifest.run_id} does not match requested run ${runId}`);
+  const checksums = verifyRunPackage(runDir, manifest);
+  const canonicalArtifacts = sortedObject(Object.fromEntries(
+    Object.entries(checksums).filter(([name]) => name !== 'manifest.json'),
+  ));
+  const unavailable = [...new Set([...(manifest.incomplete_checks || []), ...(context.unavailable_observations || [])])].sort();
+  const receipt = {
+    schema_version: 1,
+    receipt_id: `ACCEPTANCE-RECEIPT-${sha256(`${runId}:${createdAt}`).slice(0, 20).toUpperCase()}`,
+    run_id: runId,
+    property: {
+      target: manifest.target || {},
+      source_commit: context.source_commit ?? manifest.repository_commit ?? null,
+      working_tree_state: manifest.working_tree_state ?? null,
+      content_hashes: sortedObject({ ...(manifest.input_hashes || {}), ...(context.content_hashes || {}) }),
+    },
+    detectors: {
+      run: [...(manifest.detectors_run || [])].sort(),
+      skipped: [...(manifest.detectors_skipped || [])].sort((a, b) => a.detector_id.localeCompare(b.detector_id)),
+    },
+    configuration: { hash: manifest.configuration_hash ?? null },
+    observation_method: {
+      command: manifest.command,
+      arguments: normalizedArguments(manifest.argv || []),
+      target_kind: manifest.target?.kind ?? null,
+      collectors: sortedObject(context.collectors || {}),
+    },
+    toolchain: {
+      citable_version: manifest.tool_version,
+      skill_version: manifest.skill_version,
+      node_version: context.node_version || process.version,
+    },
+    external_systems: sortedObject(context.external_systems || {}),
+    execution: {
+      started_at: manifest.timestamp,
+      receipt_created_at: createdAt,
+      locale: context.locale || manifest.locale || 'und',
+      region: context.region ?? null,
+      status: manifest.status,
+      partial: manifest.status !== 'completed' || unavailable.length > 0 || (manifest.errors || []).length > 0,
+      unavailable_observations: unavailable,
+      errors: [...(manifest.errors || [])],
+    },
+    canonical_artifacts: canonicalArtifacts,
+    reproducibility: { fingerprint: '', included_fields: INCLUDED_FIELDS, excluded_environment_fields: EXCLUDED_FIELDS },
+    limitations: [
+      'Fingerprint equality establishes only equality of the declared canonical inputs, methods, tools, external-system versions, and artifacts.',
+      'Locale, region, timestamps, host identity, runtime, memory, and filesystem paths are execution context and are excluded from fingerprint equality.',
+    ],
+  };
+  receipt.reproducibility.fingerprint = sha256(canonicalJson(fingerprintPayload(receipt)));
+  receipt.receipt_hash = sha256(canonicalJson(receipt));
+  const check = validateAgainst('acceptance-run-receipt.schema.json', receipt);
+  if (!check.valid) throw new Error(`acceptance receipt violates contract: ${check.errors.join('; ')}`);
+  const output = path.join(root, '.citable', 'corpus', 'receipts', `${receipt.receipt_id}.json`);
+  writeJson(output, receipt);
+  return { receipt, output };
+}
+
+export function verifyAcceptanceReceipt(receipt) {
+  const check = validateAgainst('acceptance-run-receipt.schema.json', receipt);
+  const failures = check.valid ? [] : [...check.errors];
+  const { receipt_hash: ignored, ...unsigned } = receipt;
+  if (receipt.receipt_hash !== sha256(canonicalJson(unsigned))) failures.push('receipt hash is inconsistent');
+  if (receipt.reproducibility?.fingerprint !== sha256(canonicalJson(fingerprintPayload(receipt)))) failures.push('reproducibility fingerprint is inconsistent');
+  return { valid: failures.length === 0, failures };
+}
+
+function changed(left, right) {
+  return canonicalJson(left) !== canonicalJson(right);
+}
+
+export function compareAcceptanceReceipts(left, right) {
+  const leftCheck = verifyAcceptanceReceipt(left);
+  const rightCheck = verifyAcceptanceReceipt(right);
+  if (!leftCheck.valid || !rightCheck.valid) throw new Error(`acceptance receipt integrity failed: ${[...leftCheck.failures, ...rightCheck.failures].join('; ')}`);
+  const dimensions = {
+    property_changed: changed({ target: left.property.target, source_commit: left.property.source_commit, content_hashes: left.property.content_hashes }, { target: right.property.target, source_commit: right.property.source_commit, content_hashes: right.property.content_hashes }),
+    detector_changed: changed(left.detectors, right.detectors),
+    configuration_changed: changed(left.configuration, right.configuration),
+    observation_method_changed: changed(left.observation_method, right.observation_method),
+    tool_changed: changed(left.toolchain, right.toolchain),
+    external_system_changed: changed(left.external_systems, right.external_systems),
+  };
+  const canonicalArtifactsChanged = changed(left.canonical_artifacts, right.canonical_artifacts);
+  return {
+    receipt_a: left.receipt_id,
+    receipt_b: right.receipt_id,
+    fingerprint_equal: left.reproducibility.fingerprint === right.reproducibility.fingerprint,
+    canonical_artifacts_changed: canonicalArtifactsChanged,
+    change_dimensions: dimensions,
+    partial_runs: [left, right].filter((item) => item.execution.partial).map((item) => ({ receipt_id: item.receipt_id, status: item.execution.status, unavailable_observations: item.execution.unavailable_observations, errors: item.execution.errors })),
+    comparable: !Object.values(dimensions).some(Boolean),
+    limitation: 'Comparability identifies declared envelope differences. It does not establish causation, external-system stability, or performance on untested properties.',
+  };
+}
+
+export function readAndCompareAcceptanceReceipts(leftFile, rightFile) {
+  if (!leftFile || !rightFile) throw new Error('corpus compare-receipts requires two receipt files');
+  return compareAcceptanceReceipts(readJson(leftFile), readJson(rightFile));
+}