How the Delivery Atomic Commit Works in Archify: Safe Publishing Explained

The delivery atomic commit in Archify guarantees safe publishing by rendering a JSON specification to a temporary candidate file, generating a SHA-256 receipt, and performing a filesystem-level atomic rename only after all validation and artifact checks succeed, ensuring existing trusted outputs remain untouched if any step fails.

Archify transforms design-time JSON specifications into trusted HTML artifacts through a rigorous safety mechanism known as the delivery atomic commit. Implemented in the tt-a1i/archify repository, this three-phase pipeline ensures that corrupted or partially rendered outputs never replace valid existing files. The process is governed by the Delivery Contract, which mandates validation, deterministic receipt generation, and atomic filesystem operations.

The Delivery Contract Pipeline

The Delivery Contract in archify/references/delivery-contract.md mandates a strict "write-snapshot → validate → checksum → rename-atomically" workflow. This contract protects the published artifact from partial updates through three distinct phases.

Phase 1: Validate and Render

First, Archify reads and validates the input specification, then renders it to a temporary candidate file. This occurs in a staging directory created next to the target output path to ensure the final rename operates on the same filesystem.

Phase 2: Deterministic Receipt Generation

The artifact checker produces a receipt containing SHA-256 hashes and byte counts for both the original specification and the rendered artifact. This receipt includes validation results and composition profiles, creating an auditable trail of byte-level identity.

Phase 3: Atomic Commit

Only after the receipt passes all artifact-checking steps does Archify execute fs.renameSync(candidatePath, outputPath). Because the candidate resides on the same filesystem as the final target, this rename is atomic, replacing the old file entirely or not at all.

Implementation in commandDeliver

The core logic lives in archify/bin/archify.mjs within the commandDeliver function. This implementation enforces the delivery atomic commit through seven specific steps.

First, the function creates a staging folder adjacent to the target path. As noted in lines 40-44, this placement ensures the final rename is a single filesystem operation:

// Keep the candidate beside the target so the final rename is one
// same-filesystem commit. A render or artifact-check failure never touches
// an existing trusted output.
const stagingDirectory = fs.mkdtempSync(path.join(outputDirectory, '.archify-delivery-'));

Second, the specification is frozen into specification.snapshot.json using the wx flag to prevent overwrites (lines 70-73).

Third, the candidate is rendered and the artifact-checker runs. If either fails, reportDeliveryFailure is invoked and the function returns before any rename occurs (lines 95-108, 122-134).

Fourth, the receipt written by the checker is parsed. If parsing fails, delivery aborts (lines 140-155).

Fifth, the final receipt is generated (lines 1000-1030), containing hashes, validation counts, and optional repository evidence.

Sixth, the atomic rename occurs via fs.renameSync(candidatePath, outputPath) (lines 61-63). This guarantees the old file is replaced only when all prior steps succeeded.

Seventh, the optional --open flag triggers after the rename (lines 82-96), ensuring preview failures cannot corrupt the published artifact.

If any step throws, the finally block cleans up the staging directory (lines 9-13), leaving the original output unchanged.

Practical Usage Examples

Use the following commands to leverage the delivery atomic commit in your workflow.

Deliver a diagram with full contract enforcement:

# Render and atomically deliver an architecture diagram

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

This command reads diagram.json, validates it, renders the candidate, checks the artifact, writes a receipt, and atomically renames the candidate to output.html only if every step succeeds.

Use the optional preview flag:

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

The --open flag triggers a local OS opener after the atomic rename. Any failure to open does not affect the delivery status or corrupt the artifact.

Inspect the delivery receipt:

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

A typical receipt proves byte-level integrity:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "deliver",
  "type": "architecture",
  "output": "/abs/path/output.html",
  "specification": { "sha256": "c1a2…", "bytes": 1234 },
  "artifact":      { "sha256": "d4e5…", "bytes": 5678 },
  "validation": {
    "checksPassed": 9,
    "checkCount": 9,
    "compositionProfile": "showcase",
    "compositionStatus": "passed"
  }
}

Key Files Supporting Atomic Delivery

Understanding the delivery atomic commit requires familiarity with these source files:

• archify/references/delivery-contract.md: The human-readable specification defining the pipeline, receipt format, and safety guarantees.
• archify/bin/archify.mjs: Contains the commandDeliver function implementing the atomic commit logic.
• archify/scripts/check-render-output.mjs: The artifact checker that produces deterministic receipts.
• archify/renderers/shared/output-path.mjs: Ensures the staging directory resides on the same filesystem as the target.
• archify/open-artifact.mjs: Handles the optional --open step strictly after the atomic commit.

Summary

• The delivery atomic commit follows a strict three-phase pipeline: validate and render, generate deterministic receipt, and atomic rename.
• Safety is guaranteed by keeping the candidate in a staging directory adjacent to the target, ensuring fs.renameSync operates atomically on the same filesystem.
• Traceability comes from SHA-256 hashes and byte counts recorded in the delivery receipt, enabling full auditability of every published artifact.
• Failure isolation ensures that validation errors, rendering failures, or receipt parsing errors trigger cleanup without touching existing trusted outputs.
• The optional --open flag executes only after the atomic commit succeeds, preventing preview operations from influencing delivery outcomes.

Frequently Asked Questions

What happens if the artifact checker fails during delivery?

If the artifact checker fails, the commandDeliver function in archify/bin/archify.mjs invokes reportDeliveryFailure and returns before reaching the fs.renameSync call (lines 95-108, 122-134). The staging directory is cleaned up in the finally block, and the existing output file remains untouched.

How does Archify ensure the atomic rename is truly atomic?

Archify creates the staging directory next to the target output path using fs.mkdtempSync(path.join(outputDirectory, '.archify-delivery-')) (lines 40-44). Because the candidate and target reside on the same filesystem, fs.renameSync(candidatePath, outputPath) (lines 61-63) becomes an atomic operation at the OS level, meaning the file appears at the new path instantly without partial writes.

Can I preview the output before the atomic commit completes?

No. The --open flag documented in the Delivery Contract runs strictly after the atomic rename (lines 82-96 in archify/bin/archify.mjs). This design ensures that preview failures or manual inspection delays cannot block or corrupt the delivery process.

Where is the delivery receipt stored and what does it contain?

The receipt is generated in memory during the commandDeliver function (lines 1000-1030) and output to stdout when using the --json flag. It contains specification.sha256, artifact.sha256, byte counts, validation check results, and composition profiles, providing cryptographic proof of the exact bytes processed and rendered.

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