# How Archify's `deliver` Command Handles Failures: A Complete Guide to Safe, Atomic Delivery

> Learn how Archify's deliver command ensures safe, atomic artifact delivery. Discover its failure handling, preventing corruption and providing diagnostic receipts for automated repair.

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

---

**Archify's `deliver` command uses atomic candidate-then-commit logic with non-zero exits on failure, ensuring corrupted artifacts never overwrite good ones and always returning machine-readable diagnostic receipts for automated repair.**

The `deliver` command is Archify's final hand-off step that transforms a validated JSON specification into a self-contained HTML artifact. According to the source code in `tt-a1i/archify`, its failure handling prioritizes safety, determinism, and auditability above all else. This guide breaks down the exact mechanism, exit behaviors, and repair workflow implemented in `bin/archify.mjs` and documented across [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) and [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md).

## The Delivery Pipeline: Render, Validate, Then Commit

Archify's `deliver` command follows a strict three-phase pipeline designed to prevent partial or corrupted outputs:

### Phase 1: Candidate Generation

First, `deliver` writes a **candidate** HTML file to a temporary location. This provisional artifact is not visible to downstream consumers.

### Phase 2: Full Validation Suite

The candidate then undergoes Archify's complete artifact validation: schema checks, layout verification, composition analysis, and more. As documented in [`SKILL.md – Delivery section`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#delivery), **every check must pass** before the command proceeds.

### Phase 3: Atomic Replacement

Only upon full validation success does the candidate **atomically replace** the existing target file. This eliminates race conditions where a reader might observe a partially written file.

## Failure Behavior: Non-Zero Exits with Preserved Output

When any validation check fails, `deliver` behaves predictably:

| Behavior | Implementation |
|----------|----------------|
| Exit status | Non-zero exit code |
| Output preservation | Previous good HTML remains completely untouched |
| Receipt emission | Structured JSON receipt still printed (with `--json`) |

This guarantee is explicit in [[`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) lines 99-102](https://github.com/tt-a1i/archify/blob/main/README.md#L99): *"On failure, `validate --json` and `deliver --json` emit one JSON object"* — and that object's `ok` field is `false`.

The atomic design means you can safely rerun `deliver` repeatedly without risk of corrupting working artifacts.

## The Failure Receipt: Machine-Readable Diagnostics

Archify transforms failures from opaque errors into structured, actionable data. The JSON receipt contains a `diagnostics[]` array where each entry specifies:

- **`code`** — Machine-parseable rule identifier (e.g., `"layout/overlap"`, `"artifact/missing"`)
- **`subject`** — The specific element requiring change
- **`evidence`** — Measured data supporting the diagnosis
- **`supportedFixes`** — Repair strategies applicable to this failure

### Example Failure Receipt

```json
{
  "ok": false,
  "diagnostics": [
    {
      "code": "layout/overlap",
      "subject": "relationship-12",
      "evidence": { "overlapArea": 42 },
      "supportedFixes": ["moveLabel", "spreadPorts"]
    },
    { "code": "artifact/missing", "subject": "output", "message": "no bytes produced" }
  ],
  "error": "validation failed"
}

```

This structure enables fully automated repair pipelines: extract `subject`, apply one of the `supportedFixes`, and re-run `deliver`.

## Successful Delivery Receipt

When validation passes, the receipt confirms integrity with cryptographic hashes and byte counts:

```bash
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json \
     /tmp/workflow.html --quality showcase --json

```

```json
{
  "ok": true,
  "specification": { "sha256": "a1b2c3…", "bytes": 1234 },
  "artifact": { "sha256": "d4e5f6…", "bytes": 56789 },
  "validation": { "compositionStatus": "pass" }
}

```

Both success and failure paths emit valid JSON, making `deliver` safe for shell scripts and CI/CD systems.

## The Repair Loop: Focused Correction Strategy

Archify's failure handling extends beyond single invocations. Per [[`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md)](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#L35), the documentation prescribes a disciplined **repair loop**:

1. **Change only the diagnosed `subject`** — No scattershot edits
2. **Re-run `validate` or `deliver`** — Measure progress objectively
3. **Continue while error count reaches a new minimum**
4. **Stop and report truthfully** if two consecutive rounds fail to reduce errors

This bounded, evidence-driven approach prevents infinite fix attempts and ensures transparent handling of unresolvable issues.

## Critical Pitfall: Avoid `visual-check` on Failed Paths

The documentation explicitly warns: [*"A failed delivery preserves any previous output, so do not run `visual-check` on that path"*](https://github.com/tt-a1i/archify/blob/main/README.md#L30). Because the previous good artifact remains in place, `visual-check` would misleadingly validate stale content rather than the failed candidate.

## Key Source Files and Test Coverage

| File | Purpose |
|------|---------|
| `archify/bin/archify.mjs` | CLI entry point implementing candidate writing, validation orchestration, and atomic replacement |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Canonical delivery contract definition |
| [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md) | Complete JSON receipt schema |
| `archify/test/delivery-contract.test.mjs` | Unit tests asserting success/failure behaviors and output preservation |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines ~99–102) | User-facing summary of failure guarantees |

The test file `delivery-contract.test.mjs` specifically verifies that failed deliveries leave previous output intact — this is not merely documented behavior but tested contract.

## Summary

- **Atomic delivery** — Candidate validated before any existing file is touched
- **Non-zero exit** on any validation failure with **zero output clobbering**
- **Structured receipts** via `--json` for both success and failure cases
- **Diagnostic-rich failures** with `code`, `subject`, `evidence`, and `supportedFixes`
- **Documented repair loop** for systematic, bounded error resolution
- **Explicit warning** against `visual-check` on paths with failed deliveries

Archify's `deliver` command treats failure as a first-class scenario rather than an afterthought, enabling safe automation and reliable CI/CD integration.

## Frequently Asked Questions

### What exit code does `deliver` return on failure?

`deliver` exits with a non-zero status code. Per the source in `bin/archify.mjs` and documentation in [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md), any validation failure triggers this exit regardless of whether `--json` is used. The specific code may vary by failure type, but all non-zero values indicate unsuccessful delivery.

### Does a failed `deliver` ever corrupt my existing HTML file?

No. The atomic candidate-then-commit design ensures the previous good artifact remains completely untouched. As demonstrated in `delivery-contract.test.mjs`, the candidate is written to a separate location and only replaces the target after full validation passes. Failed runs leave the filesystem state unchanged except for temporary candidate cleanup.

### How do I programmatically respond to `deliver` failures?

Use the `--json` flag and parse the emitted receipt. Check the `ok` boolean field: when `false`, iterate through `diagnostics[]` to extract each `subject` and its `supportedFixes`. This structure enables automated repair loops without parsing human-readable error messages. The receipt format is fully specified in [`references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/references/delivery-contract.md).