# How Archify Validation and Delivery Commands Ensure Artifact Quality

> Ensure artifact quality with Archify validation and delivery commands. Our pipeline validates schemas, renders diagrams, and commits verified outputs with cryptographic receipts.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Archify validation and delivery commands guarantee artifact quality through a multi-stage pipeline that validates JSON schemas, renders diagrams, performs semantic sanity checks, and atomically commits only verified outputs with cryptographic receipts.**

The `tt-a1i/archify` repository treats artifact integrity as a first-class concern. Both the `validate` and `deliver` CLI commands implement a defensive, test-covered pipeline that separates specification parsing, schema validation, rendering, and commitment into distinct stages. This architecture ensures that only conformant, structurally sound artifacts reach your output directories.

## The Staged Quality Pipeline

Archify commands follow a strict sequence that prevents corrupted or invalid artifacts from ever reaching production paths.

### Typed Specification Loading

When invoking either command, the CLI first attempts to parse the input JSON. In `archify/bin/archify.mjs` (lines 52-61), read errors are immediately converted into structured `inputDiagnostic` objects, causing early abort before any processing begins.

### Schema Validation with Type Dispatch

The parsed document routes through `validateSchema` in `archify/renderers/shared/validator.mjs` (lines 38-45). This dispatcher selects the appropriate JSON-Schema validator—such as AJV—based on the diagram type (`architecture`, `workflow`, `dataflow`, etc.). Validation errors surface as structured diagnostics containing a **code**, **message**, **subject**, and suggested **fixes**.

### Rendering with Failure Containment

For visual output types, the CLI invokes the renderer at the requested quality level (standard, hero, etc.). According to `archify/bin/archify.mjs` (lines 91-108), any `rendererFailure` is captured as a diagnostic that halts execution before filesystem writes occur.

### Semantic Artifact Sanity Checks

After successful rendering, Archify executes `check-render-output.mjs` on the candidate artifact. As implemented in `archify/bin/archify.mjs` (lines 110-125), this script performs **semantic** and **structural** validations—including SVG well-formedness, required ID presence, and layout constraint verification. Failed checks trigger immediate candidate discard, leaving previous verified artifacts untouched.

### Atomic Staged Delivery

The `deliver` command implements transactional semantics. In `archify/bin/archify.mjs` (lines 440-465), the system creates a **temporary staging directory** (`.archify-delivery-…`) adjacent to the target output. Only after rendering and sanity checks succeed does Archify perform an atomic rename to the final output path, ensuring that partial failures never corrupt existing files.

### Verified Receipt Generation

Successful deliveries generate a JSON receipt documented in `archify/bin/archify.mjs` (lines 1020-1065). This receipt contains the **digest** of written bytes, the rendering **profile** used, and **evidence** of passed checks. Downstream tools can verify artifact provenance by inspecting this receipt.

## Defensive Error Handling

Both commands implement graceful degradation for unknown options, missing directories, or unreadable inputs. As shown in `archify/bin/archify.mjs` (lines 60-66), the CLI surfaces machine-readable error codes such as `delivery/prepare-directory` or `delivery/receipt-invalid` alongside suggested fixes, enabling reliable CI pipeline integration.

## Practical Examples

Validate a workflow specification without rendering:

```bash
archify.mjs validate workflow my-flow.json --json

# Outputs: schemaErrors, profile, and diagnostics array

```

Deliver an architecture diagram with strict quality checks:

```bash
archify.mjs deliver architecture my-arch.json --open --quality=hero

# Creates .archify-delivery-xxxx staging directory, runs renderer,

# executes check-render-output, then atomically renames to architecture.html

```

Capture and inspect the delivery receipt:

```bash
archify.mjs deliver dataflow dataflow.json --json > receipt.json
cat receipt.json | jq '.digest, .profile, .evidence'

```

## Summary

- **Schema conformity** is enforced before any rendering occurs via `validateSchema` in `validator.mjs`.
- **Structural integrity** is verified by `check-render-output.mjs` before artifacts leave the staging area.
- **Atomic commits** guarantee that only fully validated artifacts replace existing files, with staging directories preventing corruption.
- **Cryptographic receipts** provide downstream verification of artifact provenance and quality profile.
- **Machine-readable diagnostics** enable automated pipeline responses to quality failures.

## Frequently Asked Questions

### How does Archify prevent partial or corrupted artifacts from being published?

Archify uses atomic staged delivery. The `deliver` command creates a temporary `.archify-delivery-…` directory beside the target output and only renames the candidate to the final path after `check-render-output.mjs` confirms semantic and structural validity. If any stage fails, the temporary directory is discarded and existing artifacts remain untouched.

### What information does a delivery receipt contain?

According to the implementation in `archify/bin/archify.mjs` (lines 1020-1065), the JSON receipt includes the **digest** (hash) of the exact bytes written, the rendering **profile** applied, and **evidence** documenting which sanity checks passed. This allows downstream systems to verify that artifacts were produced under the expected quality constraints.

### Can validation run independently of delivery?

Yes. The `validate` command executes the same `validateSchema` logic used by `deliver` but stops after schema validation. As shown in the CLI entry point (lines 52-61 and 91-108), this allows you to check JSON conformity and receive structured diagnostics without triggering renders or filesystem writes.

### What types of errors does the schema validator detect?

The `validateSchema` dispatcher in `archify/renderers/shared/validator.mjs` (lines 38-45) detects type mismatches, missing required fields, and constraint violations specific to diagram types like `architecture`, `workflow`, or `dataflow`. Errors include structured codes, human-readable messages, and suggested fixes to expedite correction.