# How Archify Implements Atomic Commits for Artifact Delivery

> Archify ensures atomic artifact delivery using a write-then-rename pattern. Learn how Archify validates and delivers artifacts reliably with this approach.

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

---

**Archify guarantees atomic artifact delivery through a "write-then-rename" pattern that stages output in a temporary directory, validates it completely, then performs a single filesystem rename to replace the target file only if all checks pass.**

The `archify deliver` command in the `tt-a1i/archify` repository treats artifact generation as a transaction. By isolating writes to a staging area and deferring the final commit until validation succeeds, Archify ensures users never see partially rendered or corrupted output files.

## The Atomic Delivery Workflow

Archify's atomic commit mechanism follows six sequential steps implemented in `archify/bin/archify.mjs`. Each stage is designed to maximize safety and minimize the window for failure.

### 1. Create the Staging Directory

Before any rendering begins, Archify allocates a temporary directory adjacent to the final output location:

```javascript
const stagingDir = fs.mkdtempSync(path.join(outputDirectory, '.archify-delivery-'))

```

This placement at lines 838-844 in `archify/bin/archify.mjs` ensures the staging directory resides on the **same filesystem** as the target. Same-filesystem placement is a hard requirement for atomic `rename` operations on most platforms.

### 2. Freeze the Input Specification

Archify writes a read-only snapshot to [`specification.snapshot.json`](https://github.com/tt-a1i/archify/blob/main/specification.snapshot.json) inside the staging area:

```javascript
// Lines 866-871: Capture source state before rendering
fs.writeFileSync(
  path.join(stagingDir, 'specification.snapshot.json'),
  JSON.stringify(specification, null, 2)
)

```

This snapshot serves as an audit trail and prevents race conditions where the source file might change during rendering.

### 3. Render to a Candidate File

The diagram renderer outputs to a **candidate path** within the staging directory (lines 863-866), not directly to the user-specified location. This decouples the rendering process from the final commit point.

### 4. Validate Before Commit

Archify executes `check-render-output.mjs` against the candidate (lines 890-931). This script performs artifact-specific validation:

- Structural integrity checks for generated HTML/SVG
- Size and format constraints
- Cross-reference validation against the specification snapshot

**If any check fails**, the staging directory is discarded and the existing output file remains completely untouched. No partial writes ever reach the user's filesystem.

### 5. Atomic Rename as the Commit Operation

Only after successful validation does Archify perform the atomic commit:

```javascript
// Lines 1058-1060: The single atomic operation
fs.renameSync(candidatePath, outputPath)

```

On POSIX systems, this translates to a single `rename(2)` syscall. On Windows, Node.js uses `MoveFileExW` with appropriate flags. In both cases, the operation is **atomic at the filesystem level**: other processes observing `outputPath` will see either the old file or the new file, never an intermediate state.

### 6. Optional Post-Commit Opening

If the user specified `--open`, Archify delegates to `open-artifact.mjs` (lines 1080-1095) **after** the rename completes. This ordering ensures the opened file is the fully committed artifact, not a staging candidate.

## Same-Filesystem Enforcement

Atomic rename requires source and destination paths to share a filesystem mount. Archify enforces this through `archify/renderers/shared/output-path.mjs`, which:

- Resolves absolute paths for both staging and target directories
- Validates they share a common filesystem root
- Falls back with clear diagnostics if cross-device moves would otherwise occur

This prevents the non-atomic copy-then-delete fallback that Node.js would silently use for cross-filesystem renames.

## Failure Handling and Diagnostics

When the atomic rename fails, Archify emits a structured `delivery/commit` diagnostic (lines 1066-1075) and preserves all state:

- The staging directory remains for inspection
- The previous artifact stays in place
- Exit codes distinguish validation failures from commit failures

Users can manually recover by inspecting [`specification.snapshot.json`](https://github.com/tt-a1i/archify/blob/main/specification.snapshot.json) and the rejected candidate.

## Command Examples

Basic delivery with automatic atomic replacement:

```bash
archify deliver architecture diagram.json --open

```

Custom output path with same atomic guarantees:

```bash
archify deliver workflow flow.json ./my-workflow.html

```

In both commands, the actual sequence is:

1. Write to `.archify-delivery-<random>/[output-name]`
2. Run `check-render-output.mjs` validation
3. Atomically rename over existing file

The receipt file (`[output-name].receipt.json`) follows an identical staging-and-rename pattern, ensuring the artifact/receipt pair are always committed together without synchronization gaps.

## Summary

- **Staging directory creation** on the same filesystem as target (lines 838-844)
- **Specification snapshot** freezes input state before rendering (lines 866-871)
- **Candidate rendering** isolated from final output path (lines 863-866)
- **Pre-commit validation** via `check-render-output.mjs` (lines 890-931)
- **Atomic rename** as the single commit operation (lines 1058-1060)
- **Structured error handling** with `delivery/commit` diagnostics (lines 1066-1075)
- **Paired commits** for artifacts and receipts using identical patterns

## Frequently Asked Questions

### How does Archify prevent partially written artifacts?

Archify never writes directly to the target file path. Instead, it renders to a temporary candidate in a staging directory, validates the complete output, then performs a single atomic `fs.renameSync()` operation. This approach ensures that any observer of the target file sees either the previous complete version or the new complete version, never an intermediate state.

### What happens if validation fails during delivery?

Validation failures trigger immediate cleanup without touching the existing output file. The staging directory is discarded, a diagnostic message is emitted, and Archify exits with a non-zero status. The previous trusted artifact remains available at the original path, maintaining system stability even when new specifications contain errors.

### Why must the staging directory be on the same filesystem as the output?

Atomic rename operations require source and destination paths to share a filesystem mount. Cross-device moves fallback to copy-then-delete sequences, which are vulnerable to interruption and leave temporaries on failure. Archify's `output-path.mjs` module enforces same-filesystem placement to guarantee true atomicity.

### Can the atomic commit fail after validation passes?

Yes, though rarely. Race conditions (concurrent modification, permission changes, or filesystem unmounting) can cause `renameSync` to throw. Archify catches these errors at lines 1066-1075, emits a `delivery/commit` diagnostic, and preserves the staging directory for manual recovery. The original artifact remains unmodified throughout.