How Archify Implements Atomic Commits for Artifact Delivery

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:

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 inside the staging area:

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

// 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 and the rejected candidate.

Command Examples

Basic delivery with automatic atomic replacement:

archify deliver architecture diagram.json --open

Custom output path with same atomic guarantees:

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.

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