# How Archify's Atomic Delivery Contract Works: A Complete Technical Guide

> Understand how Archify's atomic delivery contract ensures diagram integrity. Learn how it prevents partial or corrupted artifacts with a filesystem move and deterministic checks.

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

---

**Archify guarantees that generated diagrams are only published when every deterministic check succeeds, using an atomic filesystem move that prevents partial or corrupted artifacts from ever reaching the public location.**

Archify's atomic delivery contract is the core reliability mechanism in the `tt-a1i/archify` repository that ensures architecture documentation is immutable and reproducible. This contract enforces a strict pipeline where specifications are frozen, validated, and committed only after passing all automated checks, producing cryptographic receipts for downstream verification. Understanding this contract is essential for maintaining trust in generated diagrams that must never display broken or intermediate renders.

## The Seven-Step Delivery Pipeline

The `archify deliver` command implements the atomic delivery contract through a deterministic sequence defined in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md).

### Candidate Preparation

Before delivery, run `archify validate` to ensure your JSON specification is well-formed and passes all schema, renderer, and composition checks. This optional but recommended step catches syntax errors early without triggering the full atomic pipeline.

### Freezing the Specification

The `deliver` command reads the specification **once** and writes those exact bytes into a *private same-directory snapshot*—a hidden candidate file that represents the immutable input for this delivery attempt. This freezing step ensures that subsequent rendering and checking operate on byte-for-byte identical input, preventing race conditions where the source file might change during processing.

### Rendering and Artifact Checking

The frozen snapshot is rendered into HTML, then the **artifact checker** executes a full suite of deterministic checks. These validations include size limits, theme containment verification, and layout rule compliance. All checks must pass before the pipeline proceeds to the commit phase.

### Atomic Commit to Public Location

Only when *all* checks pass does Archify **atomically replace** the target HTML file with the newly rendered artifact. According to the contract in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md), this replacement is implemented as a single filesystem move operation. Because it is atomic, the previous artifact remains untouched if any failure occurs during the move, ensuring zero-downtime updates and preventing partial writes from corrupting the public documentation.

### Receipt Generation

Upon successful commit, Archify writes a JSON receipt beside the output file containing cryptographic proof of the delivery. As specified in `archify/references/delivery-contract.md#L27-L33`, the receipt includes:

- `specification_sha256` and `artifact_sha256` (exact byte hashes of both files)
- Byte counts for both the specification and artifact
- Validation summary and `browser_evidence` status
- A `visual_review` placeholder for manual verification tracking

This receipt serves as immutable evidence that the artifact matches the frozen specification byte-for-byte and passed all automated checks.

### Failure Handling and Rollback

If rendering, checking, receipt creation, or the final `git-move` operation fails, the command exits with a non-zero status. The implementation removes the private snapshot and **preserves the previous trusted artifact** in the public location. As tested in `archify/test/workflow-compiler-hard-contract.test.mjs`, no partial or corrupted file ever reaches the public directory, maintaining the integrity of your documentation even during system failures.

### Optional Preview Opening

Adding the `--open` flag triggers a bounded OS opener *after* the atomic commit succeeds. As documented in `archify/references/delivery-contract.md#L67-L70`, the success or failure of this preview operation is recorded in `open.status` but does **not** affect the delivery outcome. The artifact remains published regardless of whether your local browser successfully launches.

## CLI Usage Examples

Execute the atomic delivery contract using the CLI entry point at `bin/archify.mjs`.

Validate a candidate before delivery:

```bash
node bin/archify.mjs validate diagram.json

```

Perform an atomic delivery with receipt generation:

```bash
node bin/archify.mjs deliver \
    architecture diagram.json output.html \
    --quality showcase \
    --json

```

Deliver and open only after successful atomic commit:

```bash
node bin/archify.mjs deliver \
    architecture diagram.json output.html \
    --quality showcase \
    --open

```

Inspect an already-delivered artifact without re-rendering:

```bash
node bin/archify.mjs visual-check output.html

```

Running `visual-check` after a successful delivery inspects the exact artifact and produces automated browser evidence recorded in the receipt, as detailed in `archify/references/delivery-contract.md#L35-L50`.

## Contract Guarantees and Source Implementation

The atomic delivery contract is enforced by several key source files:

- **[`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md)** — Defines the contract terms, receipt format, failure semantics, and optional `--open` behavior.
- **[`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md)** (lines 201-203) — Summarizes the atomic delivery command and its core guarantees for end users.
- **`archify/test/workflow-compiler-hard-contract.test.mjs`** — Contains test suites verifying that the atomic delivery pipeline maintains contract guarantees under failure scenarios.
- **`bin/archify.mjs`** — Implements the CLI commands (`validate`, `deliver`, `visual-check`) that orchestrate the pipeline.
- **[`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)** — The base HTML template that is atomically replaced after successful validation.

## Summary

Archify's atomic delivery contract provides deterministic, reproducible artifact publishing through these core mechanisms:

- **Immutable freezing** creates a private snapshot of the specification bytes before any processing begins.
- **All-or-nothing validation** ensures only artifacts passing every deterministic check reach the public location.
- **Atomic filesystem replacement** prevents partial or corrupted files from ever being visible to documentation consumers.
- **Cryptographic receipts** provide SHA-256 hashes and byte counts for downstream verification of specification-to-artifact integrity.
- **Graceful failure handling** preserves the previous trusted artifact and cleans up temporary snapshots when any step fails.

## Frequently Asked Questions

### What happens if the artifact checker detects a validation error?

If any deterministic check fails—whether size limits, theme containment, or layout rules—the `deliver` command exits with a non-zero status, removes the private snapshot file, and leaves the previous artifact untouched in the public location. The new render never partially overwrites the existing documentation.

### Does the `--open` flag affect whether the delivery succeeds?

No. According to `archify/references/delivery-contract.md#L67-L70`, the optional `--open` flag triggers a browser preview only *after* the atomic commit completes successfully. Whether your OS successfully opens the browser or not is recorded in `open.status` but does not trigger a rollback or failure state.

### How can I verify that a delivered artifact matches its original specification?

Each successful delivery generates a JSON receipt containing `specification_sha256` and `artifact_sha256` hashes. You can independently verify these by computing SHA-256 checksums of both files and comparing them to the receipt values stored beside the output file.

### What is the difference between `validate` and `deliver` commands?

`archify validate` performs schema and composition checks without creating artifacts or modifying the public location, making it safe for CI linting. `archify deliver` executes the full atomic pipeline including freezing, rendering, checking, atomic commit, and receipt generation, actually publishing the artifact only upon complete success.