@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/archify/test/architecture-delta.test.mjs

@@ -0,0 +1,705 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import {
+  ArchitectureDeltaError,
+  architectureDeltaChangeRows,
+  canonicalArchitectureJson,
+  compareArchitecture,
+  validateArchitectureDeltaHtml,
+} from '../delta/architecture-delta.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const cli = path.join(skillRoot, 'bin/archify.mjs');
+const baseFixture = path.join(skillRoot, 'examples/checkout-platform.base.architecture.json');
+const headFixture = path.join(skillRoot, 'examples/checkout-platform.head.architecture.json');
+const checkedArtifact = path.resolve(skillRoot, '../examples/checkout-platform-delta.html');
+const checkedReceipt = path.resolve(skillRoot, '../examples/checkout-platform-delta.receipt.json');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-delta-'));
+
+const read = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const run = (args) => spawnSync(process.execPath, [cli, ...args], { cwd: skillRoot, encoding: 'utf8' });
+
+test('architecture compare classifies authored facts separately from geometry and presentation', () => {
+  const receipt = compareArchitecture(read(baseFixture), read(headFixture));
+  assert.equal(receipt.command, 'compare');
+  assert.equal(receipt.completeness, 'complete');
+  assert.equal(receipt.proofLevel, 'authored');
+  assert.deepEqual(receipt.summary.components, {
+    added: 1,
+    changed: 1,
+    evidenceChanged: 0,
+    removed: 1,
+    moved: 1,
+  });
+  assert.deepEqual(receipt.summary.connections, {
+    added: 1,
+    changed: 2,
+    removed: 1,
+    rerouted: 1,
+  });
+  assert.equal(receipt.summary.presentationChanged, true);
+
+  const checkout = receipt.changes.components.find((change) => change.id === 'checkout');
+  assert.equal(checkout.status, 'changed');
+  assert.deepEqual(checkout.classifications, ['semantic']);
+  assert.deepEqual(checkout.changedFields, ['/sublabel']);
+
+  const queue = receipt.changes.components.find((change) => change.id === 'queue');
+  assert.equal(queue.status, 'moved');
+  assert.deepEqual(queue.classifications, ['geometry']);
+  assert.deepEqual(queue.changedFields, ['/pos']);
+
+  const authorization = receipt.changes.connections.find((change) => change.id === 'authorize-payment');
+  assert.equal(authorization.status, 'changed');
+  assert.deepEqual(authorization.classifications, ['geometry', 'topology']);
+  assert.deepEqual(authorization.changedFields, ['/from', '/fromSide', '/toSide', '/via']);
+
+  assert.deepEqual(receipt.changes.connections.find((change) => change.status === 'added').classifications, ['topology']);
+
+  const headWithBoundary = read(headFixture);
+  headWithBoundary.boundaries.push({ kind: 'region', label: 'Fraud edge', wraps: ['fraud'] });
+  const boundaryReceipt = compareArchitecture(read(baseFixture), headWithBoundary);
+  assert.deepEqual(boundaryReceipt.changes.boundaries.find((change) => change.label === 'Fraud edge').classifications, ['scope']);
+});
+
+test('legend-only changes are presentation changes and never topology changes', () => {
+  const base = read(baseFixture);
+  const head = read(baseFixture);
+  head.meta.legend = {
+    entries: {
+      security: { label: 'Trust boundary', visible: true },
+      database: { visible: false },
+    },
+  };
+
+  const receipt = compareArchitecture(base, head);
+  assert.equal(receipt.summary.presentationChanged, true);
+  assert.deepEqual(receipt.summary.components, {
+    added: 0,
+    changed: 0,
+    evidenceChanged: 0,
+    removed: 0,
+    moved: 0,
+  });
+  assert.deepEqual(receipt.summary.connections, {
+    added: 0,
+    changed: 0,
+    removed: 0,
+    rerouted: 0,
+  });
+  assert.deepEqual(receipt.changes, { components: [], connections: [], boundaries: [] });
+});
+
+test('canonical architecture ignores formatting, entity order, and set-like order', () => {
+  const original = read(baseFixture);
+  const reordered = JSON.parse(JSON.stringify(original));
+  reordered.components.reverse();
+  reordered.connections.reverse();
+  reordered.boundaries.reverse();
+  reordered.boundaries.forEach((boundary) => boundary.wraps.reverse());
+  assert.equal(canonicalArchitectureJson(reordered), canonicalArchitectureJson(original));
+});
+
+test('compare reports brand-only changes in the receipt and exact review target', () => {
+  const base = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Cache' },
+    components: [{ id: 'cache', type: 'database', label: 'Cache', pos: [100, 100], size: [160, 80] }],
+  };
+  const basePath = path.join(tmp, 'brand-base.json');
+  const headPath = path.join(tmp, 'brand-head.json');
+  const output = path.join(tmp, 'brand-delta.html');
+  for (const [before, after] of [[undefined, 'redis'], ['redis', 'postgresql'], ['redis', undefined]]) {
+    const head = structuredClone(base);
+    base.components[0].brand = before;
+    head.components[0].brand = after;
+    fs.writeFileSync(basePath, JSON.stringify(base));
+    fs.writeFileSync(headPath, JSON.stringify(head));
+
+    const result = run(['compare', 'architecture', basePath, headPath, output, '--json']);
+    assert.equal(result.status, 0, result.stderr);
+    const receipt = JSON.parse(result.stdout);
+    assert.equal(receipt.summary.components.changed, 1);
+    assert.deepEqual(receipt.changes.components[0].classifications, ['semantic']);
+    assert.deepEqual(receipt.changes.components[0].changedFields, ['/brand']);
+    const html = fs.readFileSync(output, 'utf8');
+    assert.match(html, /data-change-key="component:cache"/);
+    assert.deepEqual(validateArchitectureDeltaHtml(html, receipt), { ok: true, checksPassed: 10, checkCount: 10 });
+  }
+});
+
+test('compare reports locale-only changes as presentation changes', () => {
+  const head = read(baseFixture);
+  head.meta.locale = 'zh-CN';
+  const headPath = path.join(tmp, 'locale-head.json');
+  const output = path.join(tmp, 'locale-delta.html');
+  fs.writeFileSync(headPath, JSON.stringify(head));
+
+  const result = run(['compare', 'architecture', baseFixture, headPath, output, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const receipt = JSON.parse(result.stdout);
+  assert.equal(receipt.summary.presentationChanged, true);
+  assert.deepEqual(receipt.changes, { components: [], connections: [], boundaries: [] });
+});
+
+test('change navigator order is exact-ID based, complete, unique, and stable', () => {
+  const receipt = compareArchitecture(read(baseFixture), read(headFixture));
+  const rows = architectureDeltaChangeRows(receipt);
+  assert.deepEqual(rows.map((row) => row.key), [
+    'component:fraud',
+    'relationship:fraud-check',
+    'boundary:region:Production region',
+    'boundary:security-group:Checkout trust zone',
+    'component:checkout',
+    'relationship:authorize-payment',
+    'relationship:persist-order',
+    'component:queue',
+    'component:cache',
+    'relationship:session-read',
+    'relationship:publish-order',
+  ]);
+  assert.equal(new Set(rows.map((row) => row.key)).size, rows.length);
+  assert.equal(rows.length, receipt.changes.components.length + receipt.changes.connections.length + receipt.changes.boundaries.length);
+});
+
+test('exact identity fails closed instead of guessing relationships or unrelated systems', () => {
+  const base = read(baseFixture);
+  const missingRelationship = read(headFixture);
+  delete missingRelationship.connections[0].id;
+  assert.throws(
+    () => compareArchitecture(base, missingRelationship),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/relationship-id-required'
+      && error.details.paths.includes('/connections/0/id'),
+  );
+
+  const unrelated = read(headFixture);
+  unrelated.components = unrelated.components.map((component, index) => ({ ...component, id: `other${index}` }));
+  unrelated.connections = [];
+  unrelated.boundaries = [];
+  assert.throws(
+    () => compareArchitecture(base, unrelated),
+    (error) => error instanceof ArchitectureDeltaError && error.code === 'delta/no-shared-component-id',
+  );
+});
+
+test('evidence-only component changes keep an enabled exact review contract', () => {
+  const base = read(baseFixture);
+  const head = read(baseFixture);
+  base.components[0].sources = [{ path: 'src/entry.js', line: 1, label: 'baseline' }];
+  head.components[0].sources = [{ path: 'src/entry.js', line: 2, label: 'head' }];
+  const receipt = compareArchitecture(base, head);
+  assert.equal(receipt.changes.components.length, 1);
+  assert.equal(receipt.changes.components[0].status, 'evidence-changed');
+  assert.deepEqual(receipt.changes.components[0].classifications, ['evidence']);
+  const runtime = fs.readFileSync(path.join(skillRoot, 'delta/architecture-delta.mjs'), 'utf8');
+  assert.match(runtime, /statuses: \['added', 'changed', 'evidence-changed', 'removed', 'moved'\]/);
+});
+
+test('mixed semantic and geometry component changes retain both exact forms', () => {
+  const head = read(headFixture);
+  head.components.find((component) => component.id === 'queue').sublabel = 'durable queue v2';
+  const headPath = path.join(tmp, 'mixed-component-head.json');
+  const output = path.join(tmp, 'mixed-component-delta.html');
+  fs.writeFileSync(headPath, JSON.stringify(head));
+
+  const result = run(['compare', 'architecture', baseFixture, headPath, output, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const receipt = JSON.parse(result.stdout);
+  const queue = receipt.changes.components.find((change) => change.id === 'queue');
+  assert.equal(queue.status, 'changed');
+  assert.deepEqual(queue.classifications, ['geometry', 'semantic']);
+  const html = fs.readFileSync(output, 'utf8');
+  assert.match(html, /data-change-key="component:queue"[^>]+data-change-target-signature="g:changed:geometry,semantic\|g:moved-from:geometry,semantic"/);
+  assert.deepEqual(validateArchitectureDeltaHtml(html, receipt), { ok: true, checksPassed: 10, checkCount: 10 });
+});
+
+test('mixed semantic and geometry relationship changes retain both exact routes', () => {
+  const head = read(headFixture);
+  head.connections.find((connection) => connection.id === 'publish-order').label = 'accepted event';
+  const headPath = path.join(tmp, 'mixed-relationship-head.json');
+  const output = path.join(tmp, 'mixed-relationship-delta.html');
+  fs.writeFileSync(headPath, JSON.stringify(head));
+
+  const result = run(['compare', 'architecture', baseFixture, headPath, output, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const receipt = JSON.parse(result.stdout);
+  const publishOrder = receipt.changes.connections.find((change) => change.id === 'publish-order');
+  assert.equal(publishOrder.status, 'changed');
+  assert.deepEqual(publishOrder.classifications, ['geometry', 'semantic']);
+  const html = fs.readFileSync(output, 'utf8');
+  assert.match(html, /data-change-key="relationship:publish-order"[^>]+data-change-target-signature="g:changed:geometry,semantic\|g:moved-from:geometry,semantic\|path:changed:geometry,semantic\|path:moved-from:geometry,semantic\|text:changed:\|text:moved-from:"/);
+  assert.deepEqual(validateArchitectureDeltaHtml(html, receipt), { ok: true, checksPassed: 10, checkCount: 10 });
+});
+
+test('baseline boundary title masks stay below current components and carry delta identity', () => {
+  const documentAt = (pos, pad) => ({
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Boundary mask z-order', quality_profile: 'standard', viewBox: [600, 400] },
+    components: [{ id: 'node', type: 'backend', label: 'Current node', pos, size: [120, 60] }],
+    connections: [],
+    boundaries: [{ kind: 'region', label: 'Boundary label', wraps: ['node'], pad }],
+  });
+  const basePath = path.join(tmp, 'boundary-mask.base.json');
+  const headPath = path.join(tmp, 'boundary-mask.head.json');
+  const output = path.join(tmp, 'boundary-mask.delta.html');
+  fs.writeFileSync(basePath, JSON.stringify(documentAt([250, 200], 30)));
+  fs.writeFileSync(headPath, JSON.stringify(documentAt([224, 180], 40)));
+
+  const result = run(['compare', 'architecture', basePath, headPath, output, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const html = fs.readFileSync(output, 'utf8');
+  const delta = html.match(/<section class="canvas" data-view="delta">([\s\S]*?)<\/section>/)?.[1] || '';
+  const currentComponents = delta.indexOf('<!-- Components -->');
+  const currentNode = delta.indexOf('data-node-id="node"', currentComponents);
+  const phantomMask = delta.match(
+    /<rect data-graph-role="structural-frame-label-mask"[^>]*data-delta-state="moved-from"[^>]*data-delta-boundary-state="moved-from"[^>]*data-delta-boundary-mask-key="region:Boundary label"[^>]*\/>/,
+  )?.[0];
+  const currentNodeRect = delta.slice(currentNode).match(/<rect\b[^>]*\/>/)?.[0];
+  assert.ok(phantomMask && currentNodeRect, 'expected the phantom mask and current component rect');
+  const rect = (tag) => Object.fromEntries(
+    [...tag.matchAll(/\b(x|y|width|height)="([^"]+)"/g)].map((match) => [match[1], Number(match[2])]),
+  );
+  const maskBox = rect(phantomMask);
+  const nodeBox = rect(currentNodeRect);
+  const overlaps = maskBox.x < nodeBox.x + nodeBox.width
+    && maskBox.x + maskBox.width > nodeBox.x
+    && maskBox.y < nodeBox.y + nodeBox.height
+    && maskBox.y + maskBox.height > nodeBox.y;
+  assert.equal(overlaps, true, `expected overlap: ${JSON.stringify({ maskBox, nodeBox })}`);
+  assert.ok(delta.indexOf(phantomMask) < currentNode, 'phantom mask must paint below the current component');
+});
+
+test('same-label node id changes remain one removal plus one addition', () => {
+  const base = read(baseFixture);
+  const head = read(baseFixture);
+  const cache = head.components.find((component) => component.id === 'cache');
+  cache.id = 'session-store';
+  head.boundaries.forEach((boundary) => {
+    boundary.wraps = boundary.wraps.map((id) => (id === 'cache' ? 'session-store' : id));
+  });
+  head.connections.find((connection) => connection.id === 'session-read').to = 'session-store';
+
+  const receipt = compareArchitecture(base, head);
+  assert.equal(receipt.changes.components.find((change) => change.id === 'cache').status, 'removed');
+  assert.equal(receipt.changes.components.find((change) => change.id === 'session-store').status, 'added');
+  assert.equal(receipt.changes.components.filter((change) => change.headLabel === 'Session Cache' || change.baseLabel === 'Session Cache').length, 2);
+});
+
+test('repository mismatch fails and verified matching revisions remain evidence-bounded', () => {
+  const base = read(baseFixture);
+  const head = read(headFixture);
+  base.meta.repository = { url: 'https://github.com/example/one', revision: 'a'.repeat(40) };
+  head.meta.repository = { url: 'https://github.com/example/two', revision: 'b'.repeat(40) };
+  assert.throws(
+    () => compareArchitecture(base, head),
+    (error) => error instanceof ArchitectureDeltaError && error.code === 'delta/repository-mismatch',
+  );
+
+  head.meta.repository.url = 'https://github.com/EXAMPLE/ONE.git/';
+  const receipt = compareArchitecture(base, head, { baseVerified: true, headVerified: true });
+  assert.equal(receipt.proofLevel, 'revision-pinned');
+  assert.equal(receipt.summary.provenanceChanged, true);
+});
+
+test('portable compare retains link settings and uses the same repository identity rules', () => {
+  const base = read(baseFixture);
+  const head = read(headFixture);
+  base.meta.repository = { url: 'https://git.internal/Team/Services/repo.git', revision: 'a'.repeat(40), link_mode: 'local-only' };
+  head.meta.repository = { url: 'https://git.internal:443/Team/Services/repo.git', revision: 'b'.repeat(40), link_mode: 'local-only' };
+  const canonical = JSON.parse(canonicalArchitectureJson(base));
+  assert.equal(canonical.meta.repository.link_mode, 'local-only');
+  assert.equal(canonical.meta.repository.url, 'https://git.internal/Team/Services/repo.git');
+  assert.equal(compareArchitecture(base, head, { baseVerified: true, headVerified: true }).proofLevel, 'revision-pinned');
+  head.meta.repository.url = 'https://git.internal/team/Services/repo.git';
+  assert.throws(() => compareArchitecture(base, head), (error) => error.code === 'delta/repository-mismatch');
+  base.meta.repository = { url: 'https://gitee.com/Team/repo', revision: 'a'.repeat(40), provider: 'gitee' };
+  assert.equal(JSON.parse(canonicalArchitectureJson(base)).meta.repository.provider, 'gitee');
+});
+
+test('portable compare preserves literal SCP paths and rejects different Git locations', () => {
+  const base = read(baseFixture);
+  const head = read(headFixture);
+  for (const [url, other] of [
+    ['git@git.internal:Team/repo', 'ssh://git@git.internal/Team/repo'],
+    ['git@git.internal:Team/repo%41', 'git@git.internal:Team/repoA'],
+    ['git@git.internal:Team/repo.git.git', 'git@git.internal:Team/repo.git'],
+  ]) {
+    base.meta.repository = { url, revision: 'a'.repeat(40), link_mode: 'local-only' };
+    head.meta.repository = { url: other, revision: 'b'.repeat(40), link_mode: 'local-only' };
+    const canonical = canonicalArchitectureJson(base);
+    assert.equal(JSON.parse(canonical).meta.repository.url, url);
+    assert.equal(canonicalArchitectureJson(JSON.parse(canonical)), canonical);
+    assert.throws(() => compareArchitecture(base, head), (error) => error.code === 'delta/repository-mismatch');
+    head.meta.repository.url = url;
+    assert.equal(compareArchitecture(base, head, { baseVerified: true, headVerified: true }).proofLevel, 'revision-pinned');
+  }
+});
+
+test('compare CLI writes a deterministic three-state artifact and complete sidecar receipt', () => {
+  const first = path.join(tmp, 'first.html');
+  const second = path.join(tmp, 'second.html');
+  const result = run(['compare', 'architecture', baseFixture, headFixture, first, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const repeat = run(['compare', 'architecture', baseFixture, headFixture, second, '--json']);
+  assert.equal(repeat.status, 0, repeat.stderr);
+
+  const firstHtml = fs.readFileSync(first, 'utf8');
+  const secondHtml = fs.readFileSync(second, 'utf8');
+  assert.equal(firstHtml, secondHtml);
+  assert.equal((firstHtml.match(/<section class="canvas" data-view=/g) || []).length, 3);
+  assert.match(firstHtml, /data-view="delta">/);
+  assert.match(firstHtml, /data-node-id="cache"[^>]+data-delta-state="removed"/);
+  assert.match(firstHtml, /data-node-id="fraud"[^>]+data-delta-state="added"/);
+  assert.match(firstHtml, /data-node-id="queue"[^>]+data-delta-state="moved-from"/);
+  assert.match(firstHtml, /aria-label="Authored change review"/);
+  assert.equal((firstHtml.match(/class="change-row"/g) || []).length, 11);
+  assert.match(firstHtml, /data-change-key="component:fraud"/);
+  assert.match(firstHtml, /data-change-key="relationship:authorize-payment"/);
+  assert.match(firstHtml, /data-change-key="boundary:region:Production region"/);
+  assert.match(firstHtml, /data-change-target-signature="[^"]+"/);
+  assert.match(firstHtml, /data-delta-boundary-key="region:Production region"/);
+  assert.equal((firstHtml.match(/class="snapshot-frame"/g) || []).length, 2);
+  assert.match(firstHtml, /title="Before architecture explorer"/);
+  assert.match(firstHtml, /title="After architecture explorer"/);
+  assert.match(firstHtml, /id="export-svg"[^>]*>Export SVG</);
+  assert.match(firstHtml, /id="share-card"[^>]*>Share Card</);
+  assert.match(firstHtml, /window\.Archify\.deltaExport = \{ canonicalSvg: canonicalDeltaSvg, shareCard/);
+  assert.match(firstHtml, /canvas\.width = 1200;[\s\S]*canvas\.height = 630;/);
+  assert.match(firstHtml, /structural-frame.*stroke:var\(--delta\)!important/);
+  assert.match(firstHtml, /structural-frame.*data-delta-state="changed".*stroke-dasharray:2 3!important/);
+  assert.match(firstHtml, /data-delta-boundary-state="added".*fill:#34d399!important/);
+  assert.match(firstHtml, /delta-boundary-marker\[data-delta-state\]\{color:var\(--delta\)\}/);
+  assert.match(firstHtml, /No authored architecture changes ·.*movementSummary/);
+  assert.match(firstHtml, /font-family:"JetBrains Mono",ui-monospace/);
+  assert.doesNotMatch(firstHtml, /font-family:Inter|body\{min-width:1080px/);
+  assert.match(firstHtml, /@media\(max-width:760px\)/);
+  assert.match(firstHtml, /\.canvas svg\{min-width:720px;max-height:none\}/);
+  assert.match(firstHtml, /\.changes\{overflow-x:auto\}/);
+  assert.match(firstHtml, /const REVIEW_DWELL_MS = 1400;/);
+  assert.match(firstHtml, /prefers-reduced-motion: reduce/);
+  assert.match(firstHtml, /:not\(\[data-delta-review-current\]\)/);
+  assert.match(firstHtml, /--review-same-opacity:1;--review-change-opacity:1/);
+  assert.match(firstHtml, /--d-focus:#006b8f/);
+  assert.match(firstHtml, /document\.querySelectorAll\('#archify-compare-receipt'\)\.length !== 1/);
+  assert.match(firstHtml, /targetsMatch\(reviewSources\[index\], row, matches\)/);
+  assert.match(firstHtml, /document\.addEventListener\('visibilitychange'/);
+  assert.match(firstHtml, /window\.addEventListener\('beforeprint', overview\)/);
+  assert.match(firstHtml, /aria-current', 'step'/);
+  assert.match(firstHtml, /event\.key === 'Enter' \|\| event\.key === ' '/);
+  const deltaShell = firstHtml.replace(/<iframe\b[^>]*><\/iframe>/g, '');
+  assert.doesNotMatch(deltaShell, /localStorage|sessionStorage|history\.(?:pushState|replaceState)/);
+  assert.doesNotMatch(deltaShell, /setInterval\(/);
+  assert.doesNotMatch(deltaShell, /\b(?:SAFE|LOW RISK|MERGEABLE|NO IMPACT|VERIFIED PR)\b/i);
+
+  const receipt = JSON.parse(result.stdout);
+  const sidecar = read(path.join(tmp, 'first.receipt.json'));
+  assert.deepEqual(sidecar, receipt);
+  assert.equal(receipt.artifact.sha256, JSON.parse(repeat.stdout).artifact.sha256);
+  assert.equal(receipt.validation.checksPassed, receipt.validation.checkCount);
+  assert.equal(receipt.completeness, 'complete');
+  assert.equal(JSON.stringify(receipt).includes(tmp), false);
+  assert.deepEqual(validateArchitectureDeltaHtml(firstHtml, receipt), { ok: true, checksPassed: 10, checkCount: 10 });
+});
+
+test('checked-in Checkout compare artifact is reproducible from its authoritative inputs', () => {
+  const artifact = path.join(tmp, 'checked-artifact.html');
+  const receipt = path.join(tmp, 'checked-artifact.receipt.json');
+  const result = run([
+    'compare',
+    'architecture',
+    baseFixture,
+    headFixture,
+    artifact,
+    '--receipt',
+    receipt,
+    '--quality',
+    'showcase',
+    '--json',
+  ]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.readFileSync(artifact, 'utf8'), fs.readFileSync(checkedArtifact, 'utf8'));
+  assert.deepEqual(read(receipt), read(checkedReceipt));
+});
+
+test('compare artifact exports standalone SVG with a UTF-8 XML declaration', () => {
+  const output = path.join(tmp, 'utf8-export.html');
+  const result = run(['compare', 'architecture', baseFixture, headFixture, output, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const html = fs.readFileSync(output, 'utf8');
+  assert.ok(
+    html.includes(`'<?xml version="1.0" encoding="UTF-8"?>\\n' + new XMLSerializer().serializeToString(clone)`),
+    'the exported standalone SVG must declare its UTF-8 encoding',
+  );
+});
+
+test('artifact validation fails closed on missing, duplicate, or self-blessed review identity', () => {
+  const output = path.join(tmp, 'review-identity.html');
+  const result = run(['compare', 'architecture', baseFixture, headFixture, output, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const receipt = JSON.parse(result.stdout);
+  const html = fs.readFileSync(output, 'utf8');
+  const deltaSection = html.match(/<section class="canvas" data-view="delta">([\s\S]*?)<\/section>/)?.[1];
+  assert.ok(deltaSection);
+  const fraudTag = deltaSection.match(/<g\s+[^>]*\bdata-node-id="fraud"[^>]*>/)?.[0];
+  assert.ok(fraudTag);
+
+  const missing = html.replace(fraudTag, fraudTag.replace('data-node-id="fraud"', 'data-node-id="tampered"'));
+  assert.throws(
+    () => validateArchitectureDeltaHtml(missing, receipt),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/artifact-invalid'
+      && error.details.failures.includes('ambiguous Delta identity component:fraud'),
+  );
+
+  const duplicate = html.replace(fraudTag, `${fraudTag}${fraudTag}`);
+  assert.throws(
+    () => validateArchitectureDeltaHtml(duplicate, receipt),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/artifact-invalid'
+      && error.details.failures.includes('ambiguous Delta identity component:fraud'),
+  );
+
+  const relationshipGroup = deltaSection.match(/<g\s+[^>]*\bdata-edge-id="fraud-check"[^>]*>[\s\S]*?<\/g>/)?.[0];
+  assert.ok(relationshipGroup);
+  const duplicateCompanion = html.replace(relationshipGroup, `${relationshipGroup}${relationshipGroup}`);
+  assert.throws(
+    () => validateArchitectureDeltaHtml(duplicateCompanion, receipt),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/artifact-invalid'
+      && error.details.failures.includes('ambiguous Delta target signature relationship:fraud-check'),
+  );
+
+  const duplicateRowTag = duplicateCompanion.match(/<button class="change-row"[^>]*data-change-key="relationship:fraud-check"[^>]*>/)?.[0];
+  const storedSignature = duplicateRowTag?.match(/data-change-target-signature="([^"]+)"/)?.[1];
+  assert.ok(duplicateRowTag && storedSignature);
+  const selfBlessedSignature = [...storedSignature.split('|'), 'g:added:topology'].sort().join('|');
+  const selfBlessed = duplicateCompanion.replace(
+    duplicateRowTag,
+    duplicateRowTag.replace(`data-change-target-signature="${storedSignature}"`, `data-change-target-signature="${selfBlessedSignature}"`),
+  );
+  assert.throws(
+    () => validateArchitectureDeltaHtml(selfBlessed, receipt),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/artifact-invalid'
+      && error.details.failures.includes('ambiguous Delta target signature relationship:fraud-check'),
+  );
+
+  const missingCompanionState = html.replace(
+    relationshipGroup,
+    relationshipGroup.replace(/\sdata-delta-state="[^"]+"/, ''),
+  );
+  assert.throws(
+    () => validateArchitectureDeltaHtml(missingCompanionState, receipt),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/artifact-invalid'
+      && error.details.failures.includes('missing Delta target state relationship:fraud-check'),
+  );
+
+  const receiptNode = html.match(/<script id="archify-compare-receipt"[\s\S]*?<\/script>/)?.[0];
+  assert.ok(receiptNode);
+  const duplicateReceipt = html.replace(receiptNode, `${receiptNode}${receiptNode}`);
+  assert.throws(
+    () => validateArchitectureDeltaHtml(duplicateReceipt, receipt),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/artifact-invalid'
+      && error.details.failures.includes('expected exactly one embedded compare receipt'),
+  );
+
+  const extraDeltaSvg = html.replace(
+    '<section class="canvas" data-view="delta">',
+    '<section class="canvas" data-view="delta"><svg viewBox="0 0 1 1"></svg>',
+  );
+  assert.throws(
+    () => validateArchitectureDeltaHtml(extraDeltaSvg, receipt),
+    (error) => error instanceof ArchitectureDeltaError
+      && error.code === 'delta/artifact-invalid'
+      && error.details.failures.includes('expected exactly one root SVG in the Delta canvas'),
+  );
+});
+
+test('formatting-only input changes raw proof but not semantic hash or artifact bytes', () => {
+  const reorderedPath = path.join(tmp, 'reordered-base.json');
+  const reordered = read(baseFixture);
+  reordered.components.reverse();
+  reordered.connections.reverse();
+  reordered.boundaries.forEach((boundary) => boundary.wraps.reverse());
+  fs.writeFileSync(reorderedPath, JSON.stringify(reordered, null, 4));
+
+  const originalOut = path.join(tmp, 'canonical-original.html');
+  const reorderedOut = path.join(tmp, 'canonical-reordered.html');
+  const original = run(['compare', 'architecture', baseFixture, headFixture, originalOut, '--json']);
+  const changed = run(['compare', 'architecture', reorderedPath, headFixture, reorderedOut, '--json']);
+  assert.equal(original.status, 0, original.stderr);
+  assert.equal(changed.status, 0, changed.stderr);
+  const originalReceipt = JSON.parse(original.stdout);
+  const changedReceipt = JSON.parse(changed.stdout);
+  assert.notEqual(originalReceipt.base.rawSha256, changedReceipt.base.rawSha256);
+  assert.equal(originalReceipt.base.semanticSha256, changedReceipt.base.semanticSha256);
+  assert.equal(fs.readFileSync(originalOut, 'utf8'), fs.readFileSync(reorderedOut, 'utf8'));
+  assert.equal(originalReceipt.artifact.sha256, changedReceipt.artifact.sha256);
+});
+
+test('compare failure preserves an existing trusted artifact', () => {
+  const invalid = read(headFixture);
+  delete invalid.connections[0].id;
+  const invalidPath = path.join(tmp, 'invalid-head.json');
+  const output = path.join(tmp, 'preserved.html');
+  fs.writeFileSync(invalidPath, JSON.stringify(invalid));
+  fs.writeFileSync(output, 'trusted artifact');
+
+  const result = run(['compare', 'architecture', baseFixture, invalidPath, output, '--json']);
+  assert.notEqual(result.status, 0);
+  assert.equal(fs.readFileSync(output, 'utf8'), 'trusted artifact');
+  const receipt = JSON.parse(result.stdout);
+  assert.equal(receipt.ok, false);
+  assert.equal(receipt.diagnostics[0].code, 'delta/relationship-id-required');
+  assert.equal(fs.existsSync(path.join(tmp, 'preserved.receipt.json')), false);
+});
+
+test('compare validates raw snapshots before canonicalization can discard invalid fields', () => {
+  const invalid = read(baseFixture);
+  invalid.unknown_top_level_fact = true;
+  const invalidPath = path.join(tmp, 'invalid-raw-base.json');
+  const output = path.join(tmp, 'invalid-raw-base.html');
+  fs.writeFileSync(invalidPath, JSON.stringify(invalid));
+
+  const result = run(['compare', 'architecture', invalidPath, headFixture, output, '--json']);
+  assert.notEqual(result.status, 0);
+  assert.equal(fs.existsSync(output), false);
+  assert.equal(fs.existsSync(path.join(tmp, 'invalid-raw-base.receipt.json')), false);
+  const receipt = JSON.parse(result.stdout);
+  assert.equal(receipt.ok, false);
+  assert.equal(receipt.diagnostics[0].code, 'schema/additionalProperties');
+  assert.equal(receipt.diagnostics[0].subject.side, 'base');
+  assert.equal(receipt.diagnostics[0].subject.path, '/');
+  assert.equal(receipt.diagnostics[0].evidence.additionalProperty, 'unknown_top_level_fact');
+});
+
+test('compare commit preflights both targets before replacing a trusted pair', () => {
+  const caseRoot = fs.mkdtempSync(path.join(tmp, 'pair-target-'));
+  const output = path.join(caseRoot, 'review.html');
+  const receiptPath = path.join(caseRoot, 'review.receipt.json');
+  fs.writeFileSync(output, 'trusted html');
+  fs.mkdirSync(receiptPath);
+
+  const result = run([
+    'compare', 'architecture', baseFixture, headFixture, output,
+    '--receipt', receiptPath, '--json',
+  ]);
+
+  assert.notEqual(result.status, 0);
+  assert.equal(fs.readFileSync(output, 'utf8'), 'trusted html');
+  assert.equal(fs.statSync(receiptPath).isDirectory(), true);
+  const failure = JSON.parse(result.stdout);
+  assert.equal(failure.stage, 'commit');
+  assert.equal(failure.diagnostics[0].code, 'delta/commit-target');
+  assert.equal(failure.diagnostics[0].evidence.targetType, 'directory');
+});
+
+for (const side of ['base', 'head']) {
+  for (const initiallyValid of [true, false]) {
+    test(`compare validates captured ${side} bytes when the original becomes ${initiallyValid ? 'invalid' : 'valid'}`, () => {
+      const caseRoot = fs.mkdtempSync(path.join(tmp, 'snapshot-'));
+      const input = path.join(caseRoot, `${side}.json`);
+      const output = path.join(caseRoot, 'delta.html');
+      const receiptPath = path.join(caseRoot, 'delta.receipt.json');
+      const valid = read(side === 'base' ? baseFixture : headFixture);
+      const invalid = { ...valid, unknown_top_level_fact: true };
+      const captured = Buffer.from(JSON.stringify(initiallyValid ? valid : invalid));
+      const replacement = JSON.stringify(initiallyValid ? invalid : valid);
+      fs.writeFileSync(input, captured);
+      fs.writeFileSync(output, 'trusted html');
+      fs.writeFileSync(receiptPath, 'trusted receipt');
+      const preload = path.join(caseRoot, 'replace-after-read.cjs');
+      // 在首次读取返回时替换原文件，避免依赖定时竞争或平台专用 FIFO。
+      fs.writeFileSync(preload, `
+        const fs = require('node:fs');
+        const originalRead = fs.readFileSync;
+        fs.readFileSync = function(file, ...args) {
+          const bytes = originalRead.call(this, file, ...args);
+          if (file === ${JSON.stringify(input)}) {
+            fs.readFileSync = originalRead;
+            fs.writeFileSync(file, ${JSON.stringify(replacement)});
+          }
+          return bytes;
+        };
+      `);
+      const result = spawnSync(process.execPath, [
+        '--require', preload, cli, 'compare', 'architecture',
+        side === 'base' ? input : baseFixture,
+        side === 'head' ? input : headFixture, output, '--json',
+      ], { cwd: skillRoot, encoding: 'utf8', timeout: 30000 });
+      assert.ifError(result.error);
+      assert.equal(fs.readFileSync(input, 'utf8'), replacement);
+      const receipt = JSON.parse(result.stdout);
+      if (initiallyValid) {
+        assert.equal(result.status, 0, result.stdout + result.stderr);
+        assert.equal(receipt.ok, true);
+        assert.equal(receipt[side].rawSha256, createHash('sha256').update(captured).digest('hex'));
+        assert.equal(receipt[side].bytes, captured.byteLength);
+        assert.deepEqual(read(receiptPath), receipt);
+      } else {
+        assert.notEqual(result.status, 0);
+        assert.equal(receipt.ok, false);
+        assert.equal(receipt.diagnostics[0].code, 'schema/additionalProperties');
+        assert.equal(receipt.diagnostics[0].subject.side, side);
+        assert.equal(fs.readFileSync(output, 'utf8'), 'trusted html');
+        assert.equal(fs.readFileSync(receiptPath, 'utf8'), 'trusted receipt');
+      }
+      assert.equal(fs.readdirSync(caseRoot).some(name => name.startsWith('.archify-compare-')), false);
+    });
+  }
+}
+
+for (const side of ['base', 'head']) {
+  test(`compare reports a ${side} snapshot write failure as a preparation error`, () => {
+    const caseRoot = fs.mkdtempSync(path.join(tmp, 'snapshot-write-'));
+    const output = path.join(caseRoot, 'delta.html');
+    const receiptPath = path.join(caseRoot, 'delta.receipt.json');
+    fs.writeFileSync(output, 'trusted html');
+    fs.writeFileSync(receiptPath, 'trusted receipt');
+    const preload = path.join(caseRoot, 'fail-snapshot-write.cjs');
+    fs.writeFileSync(preload, `
+      const fs = require('node:fs');
+      const originalWrite = fs.writeFileSync;
+      fs.writeFileSync = function(file, ...args) {
+        if (String(file).endsWith(${JSON.stringify(`${side}.snapshot.json`)})) {
+          const error = new Error('simulated snapshot write failure');
+          error.code = 'ENOSPC';
+          throw error;
+        }
+        return originalWrite.call(this, file, ...args);
+      };
+    `);
+
+    const result = spawnSync(process.execPath, [
+      '--require', preload, cli, 'compare', 'architecture',
+      baseFixture, headFixture, output, '--json',
+    ], { cwd: skillRoot, encoding: 'utf8', timeout: 30000 });
+
+    assert.ifError(result.error);
+    assert.notEqual(result.status, 0);
+    const failure = JSON.parse(result.stdout);
+    assert.equal(failure.stage, 'prepare');
+    assert.equal(failure.diagnostics[0].code, 'delta/freeze-snapshot');
+    assert.equal(failure.diagnostics[0].subject.side, side);
+    assert.equal(failure.diagnostics[0].evidence.systemCode, 'ENOSPC');
+    assert.match(failure.diagnostics[0].evidence.reason, /simulated snapshot write failure/);
+    assert.deepEqual(failure.diagnostics[0].supportedFixes, [
+      'choose a writable compare output directory on the target filesystem',
+    ]);
+    assert.equal(fs.readFileSync(output, 'utf8'), 'trusted html');
+    assert.equal(fs.readFileSync(receiptPath, 'utf8'), 'trusted receipt');
+    assert.equal(fs.readdirSync(caseRoot).some(name => name.startsWith('.archify-compare-')), false);
+  });
+}