Understanding the Atomicity of the Archify Delivery Process

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

node bin/archify.mjs validate workflow candidate.json --quality showcase --json

Then execute the atomic delivery:

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 once
2. Writes an immutable snapshot (.archify-delivery-*)
3. Renders the snapshot and runs all artifact checks
4. Replaces 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: 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: 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 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. 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.

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