# Understanding the Atomicity of the Archify Delivery Process > Ensure atomic delivery with Archify. Learn how Archify guarantees all-or-nothing deployments by freezing specs, rendering artifacts, and performing checks before replacing target files. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: deep-dive - Published: 2026-08-29 --- **Archify guarantees atomic delivery by freezing specification bytes in an immutable snapshot, rendering the artifact, and only replacing the target HTML file after all deterministic checks pass, ensuring an all-or-nothing outcome for every delivery.** The `tt-a1i/archify` repository implements a rigorous pipeline where the **atomicity of the Archify delivery process** ensures that architecture artifacts are either fully validated and committed or left completely untouched. This transactional approach prevents partial writes and corrupted states by treating delivery as an operation with cryptographic verification at every stage. ## The Five-Stage Atomic Delivery Pipeline According to [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) and [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md), Archify enforces atomicity through a strict sequence that treats the delivery as a single transaction. ### Freezing the Specification After a candidate JSON file passes validation, Archify creates an immutable snapshot by writing the exact bytes to a hidden file in the same directory using the pattern `.archify-delivery-*`. As documented in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), this snapshot becomes the immutable source for all subsequent rendering operations, preventing race conditions or mid-process modifications to the specification. ### Rendering and Deterministic Verification The frozen snapshot is rendered to HTML, then subjected to deterministic checks including geometry validation, orthogonal arrow verification, and legend clearance analysis. The pipeline calculates **SHA-256 hashes** and byte counts for both the specification and rendered artifact before proceeding. This stage ensures that only artifacts meeting all quality criteria become eligible for commit. ### The Atomic Commit Mechanism Only when **all** artifact checks pass does Archify replace the target output file. If any check fails, the process aborts immediately, removes the hidden snapshot, and leaves the previously trusted HTML untouched. As defined in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md), this all-or-nothing replacement guarantees that observers never see a partially written or corrupted artifact. ### Cryptographic Receipt Generation Upon successful commit, Archify emits a deterministic receipt containing `specification_sha256` and `artifact_sha256` values that cryptographically prove the exact bytes rendered. This receipt, detailed in the delivery contract, provides immutable evidence that the delivered artifact matches the frozen specification exactly. ### Post-Commit Visual Review After the atomic commit completes, an optional visual review may run, but this non-deterministic check never alters the committed artifact. The visual-review status (`passed`, `failed`, or `skipped`) is appended to the receipt without affecting the atomic guarantee established during the commit phase. ## Executing Atomic Deliveries via CLI The atomic delivery process is exposed through the `bin/archify.mjs` entry point, which implements the `validate` and `deliver` commands. First, validate your candidate specification: ```bash node bin/archify.mjs validate workflow candidate.json --quality showcase --json ``` Then execute the atomic delivery: ```bash node bin/archify.mjs deliver workflow candidate.json output.html --quality showcase --json ``` The `deliver` command performs the following atomic sequence: 1. Reads the frozen [`candidate.json`](https://github.com/tt-a1i/archify/blob/main/candidate.json) once 2. Writes an immutable snapshot (`.archify-delivery-*`) 3. Renders the snapshot and runs all artifact checks 4. Replaces [`output.html`](https://github.com/tt-a1i/archify/blob/main/output.html) **only** when every check passes 5. Emits a receipt containing SHA-256 hashes for both spec and artifact ## Source Files Enforcing Atomic Guarantees Several key files in the `tt-a1i/archify` repository implement and verify these atomic semantics: - **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)**: Documents the high-level workflow explicitly stating that delivery "freezes the exact specification bytes… renders… and only replaces the target after all artifact checks pass." - **[`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md)**: Formalizes the atomic delivery contract, receipt format, and failure handling procedures. - **`bin/archify.mjs`**: Implements the `validate` and `deliver` CLI commands that orchestrate the atomic pipeline. - **`archify/test/repair-receipt.test.mjs`**: Contains tests verifying the delivery receipt structure and atomic replacement logic. ## Summary - **Archify's delivery process** ensures atomicity through immutable snapshots and all-or-nothing commits. - The pipeline **freezes specification bytes** in `.archify-delivery-*` files before rendering to prevent modification during processing. - **SHA-256 hashes** in the delivery receipt provide cryptographic proof of the exact bytes rendered and delivered. - Failed checks trigger immediate abort, removing the snapshot and leaving the previous artifact untouched. - Optional visual reviews occur **after** the atomic commit, ensuring they cannot compromise delivery integrity. ## Frequently Asked Questions ### What happens if an artifact check fails during delivery? If any deterministic check fails during the rendering phase, Archify immediately aborts the process, deletes the hidden `.archify-delivery-*` snapshot, and leaves the existing [`output.html`](https://github.com/tt-a1i/archify/blob/main/output.html) file untouched. This ensures that downstream consumers never receive a partially validated or corrupted artifact. ### How does Archify prevent partial or corrupt deliveries? Archify prevents partial writes by using the hidden snapshot pattern and only performing the final file replacement after all verification steps succeed. As implemented in `bin/archify.mjs`, the target file update occurs as the final operation in a chain of validations, making the delivery effectively transactional. ### Can I verify the atomic delivery after it completes? Yes. The delivery receipt emitted by the `deliver` command contains `specification_sha256` and `artifact_sha256` fields that cryptographically bind the specification to the rendered output. Downstream consumers can verify that the delivered HTML matches the frozen specification by comparing these hashes against independently calculated values. ### Does visual review affect the atomic guarantee? No. Visual review is explicitly designed to run after the atomic commit completes, as documented in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md). The review status (`passed`, `failed`, or `skipped`) is appended to the receipt metadata but cannot modify or rollback the committed artifact, preserving the all-or-nothing delivery guarantee.