How the Archify Deliver Command Implements Atomic Commits

Archify's deliver command guarantees atomic replacement of HTML artifacts by staging candidates in a temporary directory, running full validation checks, and performing a single fs.renameSync operation only after all verification steps succeed.

The deliver command in the tt-a1i/archify repository ensures that architecture documentation artifacts are replaced only when fully validated. By leveraging filesystem atomicity guarantees, it prevents partial or corrupted outputs from ever reaching production paths. This implementation follows a strict staging-and-rename pattern that keeps existing artifacts intact until the very last moment.

The Atomic Delivery Workflow

The atomic commit process in archify/bin/archify.mjs follows an eight-step pipeline that isolates all potential failure points before touching the production artifact.

Resolving the Target Output Path

The process begins with resolveOutputPath, which computes a safe output location and rejects unsafe aliases. This validation occurs in archify/renderers/shared/output-path.mjs (lines 97-104), ensuring the subsequent staging directory will reside on the same filesystem as the final target—a prerequisite for atomic rename operations.

Creating the Staging Directory

Next, the command creates a temporary staging area adjacent to the target file using fs.mkdtempSync:

stagingDirectory = fs.mkdtempSync(
  path.join(outputDirectory, '.archify-delivery-')
);

This placement in archify/bin/archify.mjs (lines 45-52) guarantees that the final fs.renameSync will be a single-filesystem operation, which is atomic on POSIX systems and NTFS.

Writing the Specification Snapshot

Before rendering begins, the command writes a frozen copy of the specification to specification.snapshot.json inside the staging area. The write uses the exclusive-write flag wx to prevent race conditions:

// In archify.mjs (lines 73-78)
fs.writeFileSync(snapshotPath, JSON.stringify(spec), { flag: 'wx' });

Rendering and Validation

The candidate artifact renders into the staging directory. If rendering fails, the candidate is discarded and the existing output remains untouched. After rendering, scripts/check-render-output.mjs runs as the final artifact check. This script must exit with status 0; otherwise, the candidate is rejected and the previous artifact persists.

The command then reads back the verified artifact and any embedded source evidence via sourceEvidenceFromArtifact.

The Atomic Rename Operation

Only after successful receipt parsing, artifact hash verification, and evidence collection does the command execute:

// In archify.mjs (lines 65-68)
fs.renameSync(candidatePath, outputPath);

Because both paths reside on the same filesystem, fs.renameSync performs an atomic replacement—readers always see either the old file or the new file, never a partial state.

Post-Commit Operations

If the user specifies --open, the opener command runs only after the atomic rename completes (see archify.mjs lines 87-100). This keeps the operation CI-friendly, ensuring that preview commands execute only after the file is fully committed.

Failure Handling and Safety Guarantees

If any step fails—whether during input reading, path resolution, directory creation, rendering, checking, or receipt parsing—the command reports failure without touching the existing artifact. The test suite in archify/test/delivery-contract.test.mjs (lines 39-44) explicitly validates this behavior, asserting that replacement occurs only after all artifact checks pass and that candidates are created in the same directory as the target.

Practical Usage Examples

# Basic delivery – writes output.html atomically

archify deliver workflow diagram.json output.html --json

# Produce a showcase-quality artifact and open it (opener runs after atomic commit)

archify deliver workflow diagram.json --quality showcase --open

# Deliver with repository root for evidence collection

archify deliver architecture spec.json arch.html --repo-root /path/to/repo

These commands guarantee that output.html is never overwritten unless the new artifact passes all validation checks. When using --json, the command returns a structured receipt containing hashes, validation results, and source evidence.

Key Implementation Files

• archify/bin/archify.mjs: Contains the commandDeliver function implementing staging, rendering, checking, receipt creation, and the atomic fs.renameSync commit (lines 45-78, 87-100).
• archify/renderers/shared/output-path.mjs: Provides safe output-path resolution and alias detection to ensure same-filesystem staging (lines 97-104).
• scripts/check-render-output.mjs: Performs the final artifact validation that must succeed before the atomic commit.
• archify/test/delivery-contract.test.mjs: Validates atomic delivery semantics, ensuring candidates are staged in the target directory and replacement happens only after checks pass (lines 39-44).

Summary

• Archify stages all candidate artifacts in a temporary directory adjacent to the target file using fs.mkdtempSync.
• The specification snapshot uses exclusive-write (wx) flags to prevent concurrent modification during the delivery process.
• All validation, including the check-render-output.mjs script, must complete successfully before any filesystem changes occur.
• The final fs.renameSync operation is atomic because source and destination reside on the same filesystem.
• If any step fails, the existing artifact remains untouched, preserving the last known good output.

Frequently Asked Questions

What makes Archify's deliver command "atomic"?

The atomicity guarantee comes from using fs.renameSync as the sole operation that exposes the new artifact to the production path. Because the staging directory is created on the same filesystem as the target (via mkdtempSync in the output directory), the rename is a single metadata operation that readers cannot observe halfway, ensuring they see either the old or new file, never a partial write.

Where does Archify store temporary files during the deliver process?

The command creates a staging directory with the prefix .archify-delivery- directly inside the target output directory, as implemented in archify/bin/archify.mjs (lines 45-52). This co-location is critical for filesystem atomicity and ensures the temporary files are cleaned up or overwritten on subsequent runs without polluting system temp directories.

How does Archify prevent partial or failed renders from replacing good outputs?

The command validates the candidate artifact through multiple checkpoints: rendering must succeed, scripts/check-render-output.mjs must exit with status 0, and receipt parsing must complete. Only then does fs.renameSync execute. If any validation fails, the staging directory is discarded without ever touching the existing output file, as tested in delivery-contract.test.mjs.

Can I automate Archify deliveries in CI/CD pipelines?

Yes. The deliver command is designed for CI environments—it returns structured JSON receipts with --json and only executes optional openers (like browsers) after the atomic commit completes. This ensures that pipeline steps depending on the artifact file will only encounter fully written, validated files.

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