# What Information Is Included in an Archify Delivery Receipt?

> Discover what information an Archify delivery receipt contains. This machine-readable JSON document cryptographically verifies your rendered HTML artifact matches the source specification.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-05

---

**An Archify delivery receipt is a deterministic, machine-readable JSON document containing eight core fields—diagram type, output path, SHA-256 hashes for both specification and artifact, validation summary, browser evidence, visual review status, and correction round count—that cryptographically verify the rendered HTML artifact matches the source specification.**

The `tt-a1i/archify` repository generates these receipts during the `deliver` command to create an immutable audit trail of every diagram rendering. Understanding the exact structure of an Archify delivery receipt is essential for automating verification pipelines and ensuring reproducible builds across architecture, workflow, sequence, dataflow, and lifecycle diagrams.

## Core Fields in the Delivery Receipt

According to the delivery contract defined in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md), every receipt contains the following standardized fields.

### Diagram Type and Output Path

The receipt identifies what was rendered and where the artifact resides:

- **`diagram_type`**: The categorical classification of the rendered diagram. Valid values are `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle`【/archify/references/delivery-contract.md#L99-L101】.
- **`output`**: The absolute filesystem path to the generated HTML artifact【/archify/references/delivery-contract.md#L101-L102】.

### Cryptographic Verification Hashes

Two SHA-256 hashes provide deterministic proof of integrity:

- **`specification_sha256`**: The cryptographic hash of the **typed JSON specification** fed into the renderer【/archify/references/delivery-contract.md#L102-L103】.
- **`artifact_sha256`**: The hash of the **final HTML/SVG artifact** after rendering and artifact checking complete【/archify/references/delivery-contract.md#L103-L104】.

These hashes ensure that any verification tool can confirm the artifact was generated from the exact source specification without tampering.

### Validation and Quality Metrics

The **`validation`** field contains a human-readable summary string formatted as `<checks>/<total> <profile>, <errors> errors, <warnings> warnings`. This indicates the source passed all Clean-Flow gates for the specified quality profile (e.g., `showcase` or `standard`)【/archify/references/delivery-contract.md#L104-L105】.

### Evidence and Review Tracking

The receipt distinguishes between automated and human verification:

- **`browser_evidence`**: Records the outcome of the optional `visual-check` step. Values are `passed`, `failed`, or `skipped`, reflecting automated Chrome/Chromium evidence collection【/archify/references/delivery-contract.md#L105-L107】.
- **`visual_review`**: Captures **perceptual** human review outcomes (`passed`, `failed`, or `skipped (image reader unavailable)`). This field is recorded separately from `browser_evidence` and is never inferred deterministically【/archify/references/delivery-contract.md#L107-L109】.

### Workflow Correction History

The **`correction_rounds`** field indicates how many focused correction iterations the workflow performed before final delivery. The contract caps this value at `0`, `1`, or `2`【/archify/references/delivery-contract.md#L108-L110】.

## Delivery Receipt Format and Failure Handling

The receipt is emitted as a **single JSON object** only when the delivery pipeline (render → artifact checker) succeeds. However, failure handling preserves critical metadata:

- **Failure preservation**: If any stage fails, the receipt still records the SHA-256 of the **previous** trusted artifact and marks the delivery status as non-zero (the CLI exits with an error)【/archify/references/delivery-contract.md#L11-L14】.
- **Diagnostics array**: Failed deliveries include a `diagnostics[]` array containing rule codes and repair suggestions, as documented in the CHANGELOG【CHANGELOG.md#L65-L70】.
- **Exclusions**: The receipt deliberately excludes screenshots, side-car files, or visual-review judgments. These assets are written alongside the HTML artifact but referenced only by the status flags within the receipt.

## Generating and Reading Delivery Receipts

You produce receipts using the CLI entry point at `archify/bin/archify.mjs`.

### Generate a Standard Delivery Receipt

```bash
node bin/archify.mjs deliver architecture examples/web-app.json \
  /tmp/web-app.html --quality showcase --json

```

This command outputs a JSON receipt to stdout containing the complete field set.

### Sample Receipt Structure

```json
{
  "diagram_type": "architecture",
  "output": "/tmp/web-app.html",
  "specification_sha256": "a1b2c3d4e5f6…",
  "artifact_sha256": "f6e5d4c3b2a1…",
  "validation": "9/9 showcase, 0 errors, 0 warnings",
  "browser_evidence": "passed",
  "visual_review": "skipped (image reader unavailable)",
  "correction_rounds": 0
}

```

The SHA-256 values provide deterministic fingerprints of both the source JSON and the final HTML file.

### Running Automated Browser Evidence

To update `browser_evidence` after delivery, use the visual-check command:

```bash
node bin/archify.mjs visual-check /tmp/web-app.html --json

```

This generates side-car PNG files and produces a **new** receipt (the original delivery receipt remains immutable).

## Summary

- An Archify delivery receipt contains eight mandatory fields: `diagram_type`, `output`, `specification_sha256`, `artifact_sha256`, `validation`, `browser_evidence`, `visual_review`, and `correction_rounds`.
- SHA-256 hashes cryptographically link the rendered artifact to its source specification, enabling reproducible verification.
- The receipt distinguishes between automated browser evidence and human perceptual review, storing these as separate status flags.
- Failed deliveries preserve the previous artifact's hash and append a `diagnostics[]` array with structured repair suggestions.
- The JSON format is deterministic and machine-readable, designed for integration in CI/CD pipelines within the `tt-a1i/archify` ecosystem.

## Frequently Asked Questions

### What happens to the delivery receipt if the delivery pipeline fails?

If the render or artifact checker stages fail, the CLI still emits a receipt containing the SHA-256 of the **previous** trusted artifact rather than a new hash. The receipt includes a non-zero exit status and a `diagnostics[]` array with specific rule codes and repair suggestions to guide remediation【CHANGELOG.md#L65-L70】.

### Does the delivery receipt contain screenshots or visual artifacts?

No. The receipt contains only status flags (`browser_evidence` and `visual_review`) and never includes actual screenshots, side-car files, or visual-review judgments. These binary assets are written to the filesystem alongside the HTML output but are referenced only indirectly through the receipt's status fields【/archify/references/delivery-contract.md#L107-L109】.

### How does the correction_rounds field work in Archify?

The `correction_rounds` field tracks how many focused correction iterations the workflow performed before final delivery, with valid values of `0`, `1`, or `2`. The delivery contract explicitly caps this at two rounds to prevent infinite loops, ensuring the receipt remains deterministic and bounded【/archify/references/delivery-contract.md#L108-L110】.

### What is the difference between browser_evidence and visual_review?

**`browser_evidence`** captures automated Chrome/Chromium validation results (`passed`, `failed`, or `skipped`), while **`visual_review`** records human perceptual assessment outcomes. These fields are strictly separated—`visual_review` must be recorded separately and is never inferred from the automated checks, ensuring the receipt distinguishes between machine-generated and human judgments【/archify/references/delivery-contract.md#L105-L109】.