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

> Learn how Archify's delivery atomic commit ensures safe publishing with file validation and atomic renames. Protect your trusted outputs with this robust system.

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

---

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

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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/diagram.json), validates it, renders the candidate, checks the artifact, writes a receipt, and atomically renames the candidate to [`output.html`](https://github.com/tt-a1i/archify/blob/main/output.html) only if every step succeeds.

Use the optional preview flag:

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

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

```

A typical receipt proves byte-level integrity:

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