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

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.

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, 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:

node bin/archify.mjs validate diagram.json

Perform an atomic delivery with receipt generation:

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

Deliver and open only after successful atomic commit:

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

Inspect an already-delivered artifact without re-rendering:

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 — Defines the contract terms, receipt format, failure semantics, and optional --open behavior.
• 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 — 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}