# Archify Deliver Command: Atomic Commit and Receipt Generation Explained

> Learn how the Archify deliver command ensures atomic commits and generates cryptographic receipts. Validate artifacts and prove your transactions with Archify.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-13

---

**The `archify deliver` command guarantees atomic file updates by validating artifacts before swapping them into place and emits a cryptographic receipt proving the transaction.**

Archify is a Node.js-based diagram generation tool that converts typed JSON specifications into deterministic HTML and SVG visualizations. The `deliver` command in `tt-a1i/archify` implements a strict **render → validate → deliver** workflow that ensures only fully-verified artifacts ever replace existing files, accompanied by machine-readable receipts that serve as immutable proof of validation.

## How the Archify Deliver Command Implements Atomic Commit

The atomic delivery mechanism prevents corrupted or invalid artifacts from ever reaching production. In `archify/bin/archify.mjs`, the `commandDeliver` function orchestrates this process through a two-phase commit strategy.

**The atomic write sequence works as follows:**

1. **Candidate Generation** – The renderer writes the new artifact to a temporary file adjacent to the target path (e.g., `web-app.html.tmp`)
2. **Validation Gate** – `scripts/check-render-output.mjs` runs composition checks (label clearance, route rhythm, etc.) via `checkerDiagnostics`
3. **Atomic Swap** – Only upon passing all checks does the tool rename the candidate into place, replacing the existing file in a single filesystem operation
4. **Receipt Emission** – A JSON receipt containing SHA-256 hashes and validation metadata is printed to stdout

If any validation step fails, the candidate file is discarded and the existing artifact remains untouched. This pattern is also used in `commitComparePair` for delta comparisons, ensuring that three-panel diff views are only published after successful validation of both base and head snapshots.

## Machine-Readable Receipt Structure and Verification

Every successful delivery produces a receipt that serves as cryptographic evidence of the transaction. The receipt format is defined in [`archify/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/README.md) and [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), implemented in the delivery logic at lines 105-112 of `archify/bin/archify.mjs`.

**A standard receipt contains:**

- **Specification Hash** – SHA-256 of the source JSON IR and byte count
- **Artifact Hash** – SHA-256 of the generated HTML/SVG output
- **Validation Summary** – Checks passed versus total (e.g., 42/45), composition profile (e.g., "signal-flow"), and pass status
- **Source Evidence** – When the artifact contains `<script id="archify-source-evidence-data">` markers, `sourceEvidenceFromArtifact` extracts repository URL, revision SHA, and reference counts

This receipt enables downstream CI/CD pipelines to verify that deployed diagrams match approved specifications exactly, without re-running the full rendering pipeline.

## Practical Usage Examples

### Basic Delivery with Receipt

Generate an architecture diagram and atomically commit it with a validation receipt:

```bash
npx archify.mjs deliver architecture examples/web-app.json web-app.html --json --open

```

**Resulting receipt structure:**

```json
{
  "schemaVersion": 1,
  "ok": true,
  "command": "deliver",
  "type": "architecture",
  "input": "/path/to/examples/web-app.json",
  "output": "/path/to/web-app.html",
  "specification": { "sha256": "…", "bytes": 1234 },
  "artifact": { "sha256": "…", "bytes": 5678 },
  "validation": {
    "checksPassed": 42,
    "checkCount": 45,
    "compositionProfile": "signal‑flow",
    "compositionStatus": "pass"
  },
  "evidence": {
    "verified": true,
    "repository": "https://github.com/example/repo",
    "revision": "a1b2c3d",
    "references": 3
  }
}

```

### Atomic Comparison with Commit

Produce a delta view between architecture versions with dual validation:

```bash
npx archify.mjs compare architecture base.json head.json delta.html --receipt delta.receipt.json --json

```

This creates both [`delta.html`](https://github.com/tt-a1i/archify/blob/main/delta.html) (a three-panel comparison view) and [`delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/delta.receipt.json) containing semantic hashes for both snapshots and a combined validation summary.

## Validation and Renderer Isolation

Before any atomic commit occurs, Archify isolates the rendering process to prevent environment pollution. The `runNode` function spawns the actual diagram generation (`rendererPath('architecture')`, etc.) in a minimal child process environment (`rendererEnv`).

**Error handling follows strict boundaries:**

- **Renderer Failures** – Captured as structured `rendererFailure` diagnostics without writing partial output
- **Composition Checks** – Performed by `scripts/check-render-output.mjs` after rendering but before the atomic rename
- **Quality Profiles** – The `--quality` flag (standard or showcase) sets `ARCHIFY_QUALITY_PROFILE` to toggle visual presets without affecting validation logic

This architecture ensures that validation errors never corrupt the existing production artifact, maintaining system stability even when rendering edge cases or malformed input JSON.

## Summary

- **Atomic Delivery** – `commandDeliver` in `archify/bin/archify.mjs` uses a candidate-file-and-rename pattern to guarantee all-or-nothing updates
- **Cryptographic Receipts** – Every delivery emits JSON containing SHA-256 hashes, validation metrics, and optional source evidence for audit trails
- **Validation Gates** – `scripts/check-render-output.mjs` runs composition checks before any file swap occurs
- **Process Isolation** – Rendering occurs in sanitized child processes (`rendererEnv`) to contain failures
- **Delta Support** – The same atomic semantics apply to `commitComparePair` for architecture diff generation

## Frequently Asked Questions

### What happens if validation fails during the deliver command?

If `scripts/check-render-output.mjs` detects composition errors or the renderer returns a non-zero exit code, `commandDeliver` discards the candidate file and exits without modifying the target path. The existing artifact remains intact, and the CLI returns structured error diagnostics instead of a receipt.

### How does the receipt provide cryptographic proof of delivery?

The receipt includes SHA-256 hashes of both the input specification and final artifact bytes, generated after validation but before the atomic rename. Because the hash captures the exact content that passed validation, any subsequent modification to the file would invalidate the receipt signature, enabling third-party verification of the delivered artifact's integrity.

### Can I use atomic delivery for comparing architecture versions?

Yes. The `compare` sub-command uses `commitComparePair` (lines 84-111 in `archify/bin/archify.mjs`) to apply the same atomic semantics to three-panel diff generation. It validates both base and head snapshots before writing the comparison view, ensuring that delta.html only contains successfully rendered comparisons.

### Where is the atomic commit logic implemented?

The core atomic delivery logic resides in `archify/bin/archify.mjs` within the `commandDeliver` function (lines 84-111). This module coordinates the renderer environment, validation checks via `runNode`, and the final filesystem operations that commit the validated candidate to its target location.