# How the Archify Deliver Command Implements Atomic Commits

> Learn how Archify's deliver command ensures atomic commits through temporary staging, validation, and a final rename operation, guaranteeing safe HTML artifact replacement.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-05

---

**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`:

```js
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`](https://github.com/tt-a1i/archify/blob/main/specification.snapshot.json) inside the staging area. The write uses the exclusive-write flag `wx` to prevent race conditions:

```js
// 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:

```js
// 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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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.