# Archify Delivery Contract and Atomic Commit Behavior Explained

> Understand the Archify delivery contract's three-phase pipeline—validate render deterministic receipt generation and atomic commit—ensuring reliable HTML artifact publishing.

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

---

**The Archify delivery contract is a three-phase pipeline—validate and render, deterministic receipt generation, and atomic commit—that guarantees HTML artifacts are only published after passing all validation, rendering, and artifact-checking steps.**

The **Archify delivery contract** governs how the tt-a1i/archify tool transforms JSON specifications into trusted HTML artifacts. This contract ensures that no corrupted, partially rendered, or invalid output ever replaces an existing trusted artifact, using filesystem-level atomic operations to enforce safety.

## What the Archify Delivery Contract Specifies

The contract defines three sequential phases that every delivery must complete:

- **Validate and render** – The JSON specification is parsed, validated against its schema, and rendered to a temporary candidate file.
- **Deterministic receipt** – A receipt containing SHA-256 hashes and byte counts for both the original specification and the rendered artifact is generated.
- **Atomic commit** – Only when the receipt passes all artifact-checking steps does Archify perform a filesystem rename from candidate to final output.

This structure guarantees that **failure at any stage leaves the existing output untouched**. The contract is documented in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md) and implemented in `archify/bin/archify.mjs`.

## How Atomic Commit Works in the Source Code

The atomic commit mechanism centers on the `commandDeliver` function in `archify/bin/archify.mjs`. The implementation follows a strict ordering that makes failure modes safe by design.

### Staging Directory Creation

Archify creates a staging folder adjacent to the target output path. This placement ensures the final rename is a single atomic filesystem operation on the same device.

```js
// 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-'));

```

Lines 40-44 of `archify.mjs` establish this invariant. If the staging directory cannot be created, the delivery aborts immediately.

### Specification Freezing and Candidate Rendering

The tool writes an immutable snapshot of the specification using the `wx` flag (lines 70-73):

```js
// specification.snapshot.json written with 'wx' — fails if exists
fs.writeFileSync(snapshotPath, JSON.stringify(specification, null, 2), { flag: 'wx' });

```

The renderer then produces the candidate HTML. If rendering fails, `reportDeliveryFailure` is invoked and the function returns before any filesystem state changes (lines 95-108).

### Artifact Checking and Receipt Parsing

The artifact checker (`archify/scripts/check-render-output.mjs`) validates the candidate against nine composition and quality checks. Failure here likewise triggers early abort (lines 122-134).

The checker writes a receipt that `commandDeliver` must parse successfully. Invalid receipt syntax prevents delivery (lines 140-155):

```js
const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
if (!receipt.ok) {
  return reportDeliveryFailure('Artifact checks failed', receipt);
}

```

### The Atomic Rename Operation

Only after all prior steps succeed does Archify execute the critical operation (lines 61-63):

```js
fs.renameSync(candidatePath, outputPath);

```

Because `candidatePath` and `outputPath` reside on the same filesystem, this rename is atomic—observers see either the old file or the new file, never a partial write or corrupted intermediate state.

### Cleanup and Optional Preview

A `finally` block (lines 9-13) removes the staging directory regardless of success or failure. The optional `--open` flag triggers only after the rename completes (lines 82-96), ensuring that preview failures cannot corrupt the published artifact.

## Receipt Format and Traceability

The delivery contract mandates a deterministic receipt that enables byte-level auditing. A typical receipt structure:

```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"
  }
}

```

The `specification_sha256` and `artifact_sha256` fields provide cryptographic proof of identity. The `checksPassed` and `checkCount` fields demonstrate that all validation rules were satisfied before commit.

## Practical Delivery Commands

### Standard Delivery with Contract Enforcement

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

```

This executes the full pipeline: validation, rendering, artifact checking, receipt generation, and atomic rename. The `--json` flag outputs the receipt for programmatic inspection.

### Delivery with Post-Commit Preview

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

```

The `--open` flag invokes `archify/open-artifact.mjs` only after the atomic rename succeeds. Preview failures are isolated from delivery success.

## Key Files in the Atomic Commit Implementation

| Path | Role |
|------|------|
| [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md) | Human-readable specification of the delivery pipeline, receipt format, and safety guarantees. |
| `archify/bin/archify.mjs` | CLI implementation; `commandDeliver` function enforces the atomic commit workflow. |
| `archify/scripts/check-render-output.mjs` | Artifact checker that produces the deterministic receipt required for commit. |
| `archify/renderers/shared/output-path.mjs` | Output path resolution ensuring staging and target locations share a filesystem. |
| `archify/open-artifact.mjs` | Post-commit preview handler; never influences delivery outcome. |

## Summary

- The **Archify delivery contract** is a three-phase pipeline (validate/render, receipt generation, atomic commit) that prevents partial or failed deliveries from corrupting published artifacts.
- **Atomic commit** is implemented via same-filesystem staging and `fs.renameSync`, guaranteeing that observers see either the old or new file, never an intermediate state.
- **Receipts** provide cryptographic traceability through SHA-256 hashes of both specification and artifact, plus validation metadata.
- The **`--open` preview** runs strictly after commit, isolating UI failures from delivery integrity.
- All safety logic resides in `archify/bin/archify.mjs` with the contract documented at [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md).

## Frequently Asked Questions

### What happens if the artifact checker fails during delivery?

Archify aborts immediately and leaves the existing output unchanged. The `reportDeliveryFailure` function is invoked (lines 95-108, 122-134 of `archify.mjs`), the staging directory is cleaned up in the `finally` block, and the atomic rename never executes.

### Why does Archify use `fs.renameSync` instead of a copy operation?

`fs.renameSync` on the same filesystem is atomic—no observer can see a partially written file. A copy operation would risk exposing incomplete data if interrupted. The staging directory placement adjacent to the target ensures this atomicity guarantee.

### Can I verify that a delivered artifact matches its specification?

Yes. The receipt contains `specification.sha256` and `artifact.sha256` fields that cryptographically bind the input JSON to the output HTML. Recalculate these hashes to verify integrity or audit historical deliveries.

### Does the `--open` flag affect delivery success?

No. The optional preview implemented in `archify/open-artifact.mjs` executes only after the atomic rename completes (lines 82-96). Preview failures are logged but do not alter the delivery status or the committed artifact.