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

> Understand the Architecture Delta receipt format and learn to parse Archify comparison results. This JSON document details detected changes between architecture snapshots for audits.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json) demonstrates a real comparison output:

```json
{
  "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

```javascript
// 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

```bash

# 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

```html
<!-- 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`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json) | Full machine-readable receipt for a real "compare" run |
| [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/.receipt.json) extension, as seen in [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.