Architecture Delta Receipt Format: How to Read and Parse Archify Comparison Results

The Architecture Delta receipt is a machine-generated JSON document that summarizes the result of an Archify "compare" operation, providing a deterministic, audit-ready view of every change detected between two validated architecture snapshots.

This guide explains the Architecture Delta receipt format and how to interpret its fields for programmatic consumption, CI gating, and human review. The receipt format is implemented in the tt-a1i/archify repository and serves as the canonical output for all architecture comparison workflows.

Core Sections of an Architecture Delta Receipt

Every receipt contains seven primary sections. Understanding each section lets you extract exactly the information your workflow needs.

Summary

The summary field reports high-level health of the comparison. Key fields include:

• ok – boolean indicating overall success
• checksPassed – number of validation checks that passed
• checkCount – total number of checks executed
• validation – nested object with composition and artifact results

Changes

The changes section contains the detailed delta for components and connections. Each element includes:

Field	Description
id	Unique identifier for the element
baseLabel / headLabel	Names in the base and head snapshots
status	One of: added, removed, changed, moved, rerouted
changedFields	JSON Pointer paths to modified fields (e.g., "/sublabel")
classifications	Array categorizing the change type (e.g., ["semantic"], ["geometry"])

Identity

The identity section stores paths used to locate elements inside the source IR:

• components
• connections
• boundaries

View

The view section provides rendering hints, primarily the visualPreset field that indicates which visual preset was applied during generation.

Limitations

This section contains disclaimers about what the receipt does not prove, such as "Authored Architecture IR only; no runtime impact…"

Artifact

Cryptographic verification data for the generated HTML artifact:

• sha256 – hash of the artifact
• bytes – size in bytes

Validation

Detailed validation results including baseComposition and headComposition status.

Status Values Explained

The Architecture Delta receipt uses five status values to classify changes:

added – Element appears only in the head snapshot.

removed – Element was present only in the base snapshot.

changed – Element exists in both snapshots but fields differ; changedFields enumerates JSON-pointer paths.

moved – Element keeps logical identity but geometric placement changed; changedFields lists geometry fields like "/pos".

rerouted – A connection's routing (via points, side, or label) changed.

These statuses let CI pipelines and PR reviewers instantly see what changed without parsing full architecture JSON.

Complete Receipt Example

The file examples/checkout-platform-delta.receipt.json demonstrates a real comparison output:

{
  "changes": {
    "components": [
      {
        "id": "cache",
        "baseLabel": "Session Cache",
        "status": "removed",
        "classifications": ["semantic"],
        "changedFields": []
      },
      {
        "id": "checkout",
        "baseLabel": "Checkout API",
        "headLabel": "Checkout API",
        "status": "changed",
        "classifications": ["semantic"],
        "changedFields": ["/sublabel"]
      },
      {
        "id": "queue",
        "baseLabel": "Order Events",
        "headLabel": "Order Events",
        "status": "moved",
        "classifications": ["geometry"],
        "changedFields": ["/pos"]
      }
    ],
    "connections": [
      {
        "id": "authorize-payment",
        "base": {"from":"orders","to":"payments","label":"authorize"},
        "head": {"from":"fraud","to":"payments","label":"authorize"},
        "status": "changed",
        "classifications": ["geometry","topology"],
        "changedFields": ["/from","/fromSide","/toSide","/via"]
      }
    ]
  },
  "validation": {
    "checksPassed": 28,
    "checkCount": 28,
    "baseComposition": "pass",
    "headComposition": "pass"
  }
}

This receipt shows: the cache component was removed, checkout changed its sub-label, queue moved on the diagram, and authorize-payment was rerouted with updates to its source node, side, and path.

How to Parse Architecture Delta Receipts Programmatically

List Added Components

// Read a receipt and list all added components
import { readFileSync } from 'fs';

const receipt = JSON.parse(
  readFileSync('examples/checkout-platform-delta.receipt.json', 'utf8')
);

const added = receipt.changes.components.filter(c => c.status === 'added');
console.log('Added components:', added.map(c => c.id));

CI Gate: Validate Receipt Health

# Fail the build if any validation check failed

node -e "
  const receipt = JSON.parse(require('fs').readFileSync('examples/checkout-platform-delta.receipt.json'));
  if (!receipt.ok || receipt.validation.checksPassed !== receipt.validation.checkCount) {
    console.error('❌ Architecture Delta validation failed');
    process.exit(1);
  }
  console.log('✅ Architecture Delta passed');
"

Embed Receipt in Documentation

<!-- Include receipt summary for reviewers -->
<p><strong>Architecture Delta receipt</strong></p>
<pre>
{
  "ok": true,
  "validation": { "checksPassed": 28, "checkCount": 28 }
}
</pre>

Source Files and Implementation Details

File	Role
examples/checkout-platform-delta.receipt.json	Full machine-readable receipt for a real "compare" run
examples/checkout-platform-delta.html	Interactive HTML artifact visualizing the delta
archify/test/repair-receipt.test.mjs	Test suite validating receipt structure and error handling
scripts/package-smoke.mjs	CLI code that loads receipts and validates mode and required fields

The test suite in archify/test/repair-receipt.test.mjs enforces schema compliance, ensuring receipts remain parseable across Archify versions. The scripts/package-smoke.mjs loader throws on mismatched mode or missing fields, providing early failure for malformed receipts.

Using Receipts in CI/CD and Review Workflows

The Architecture Delta receipt format supports three primary use cases:

1. Programmatic consumption – Parse the JSON and iterate over changes.components and changes.connections to trigger downstream automation.

2. CI gating – Assert receipt.ok === true and receipt.validation.checksPassed === receipt.validation.checkCount before allowing deploys.

3. Human review – Display the receipt alongside the generated HTML (examples/checkout-platform-delta.html) to let reviewers verify that only intended facts changed.

Because the receipt is typed (schema v1) and signed by a SHA-256 hash of the artifact, it serves as immutable evidence in PR comments, release notes, or audit logs.

Summary

• The Architecture Delta receipt is a JSON document produced by Archify "compare" operations, located at paths like examples/checkout-platform-delta.receipt.json.
• Five status values—added, removed, changed, moved, rerouted—classify every component and connection change.
• The changedFields array uses JSON Pointer syntax to pinpoint exact modifications.
• Validation fields enable automated CI gates; the artifact.sha256 field enables cryptographic verification.
• Source files including archify/test/repair-receipt.test.mjs and scripts/package-smoke.mjs demonstrate production usage patterns.

Frequently Asked Questions

What is the file extension for an Architecture Delta receipt?

Architecture Delta receipts use the .receipt.json extension, as seen in examples/checkout-platform-delta.receipt.json. This dual extension indicates both the JSON format and the receipt document type.

How does the receipt differ from the HTML artifact?

The receipt is machine-readable JSON containing structured change data; the HTML artifact (examples/checkout-platform-delta.html) is a visual rendering for human review. The receipt supplies the "✔ 9/9 checks" badge displayed in the HTML, and its artifact.sha256 field cryptographically binds the two files together.

Can I trust the receipt if ok is true but some checks failed?

No. Always verify that receipt.validation.checksPassed === receipt.validation.checkCount. The ok field indicates the comparison operation completed, not that all validation gates passed. The test suite in archify/test/repair-receipt.test.mjs enforces this distinction.

Which fields appear in changedFields for a moved component?

For a moved status, changedFields typically contains geometry paths like "/pos". For a changed status, it contains semantic paths like "/sublabel". The classifications array—["semantic"], ["geometry"], or ["geometry","topology"]—indicates which categories of change are present.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}