# Archify Artifact Check Validation Explained: The Three-Stage Pipeline

> Learn how Archify artifact check validation ensures diagram accuracy with its three-stage pipeline: schema validation, composition validation, and receipt synthesis.

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

---

**Archify validates every generated diagram through schema validation, composition validation, and receipt synthesis, producing a machine-readable receipt that serves as the single source of truth for downstream tooling.**

The **Archify artifact check validation** system ensures that every diagram rendered by the tool meets strict quality and integrity standards. This validation pipeline lives in the `tt-a1i/archify` repository and produces deterministic, cryptographically verifiable receipts that CLI tools, galleries, and automated tests can consume uniformly.

## The Three Stages of Validation

Archify's validation pipeline consists of three tightly-coupled stages. Each stage feeds into the next, culminating in a comprehensive receipt document.

### Schema Validation

The first stage validates the **JSON-IR** (intermediate representation) produced during diagram authoring against a generated **AJV schema** tailored to the diagram type—whether workflow, architecture, data-flow, or another supported variant.

The core function `validateSchema` in `archify/renderers/shared/validator.mjs` performs this check:

```javascript
// archify/renderers/shared/validator.mjs#L38-L45
import { validateSchema } from './shared/validator.mjs';

try {
  validateSchema('workflow', diagramJson);
} catch (e) {
  // e is a diagnostic error containing subject, evidence, supportedFixes…
  console.error(e.diagnostics);
}

```

When validation fails, errors transform into diagnostic objects containing:
- A **subject** identifying the problematic element
- **Evidence** describing the failure
- **Supported fixes** (e.g., "remove unsupported property …")

### Composition Validation

After rendering to HTML/SVG, Archify runs a **layout validator** that inspects geometric relationships. This composition validation checks:
- Line crossings
- Border runs
- Segment lengths
- Label clearances

The composition checks are implemented in individual renderers such as `archify/renderers/dataflow/render-dataflow.mjs`. The output is a **composition record** with `profile`, `status`, `metrics`, and `issues` fields.

### Receipt Synthesis

The final stage merges validation results into a deterministic receipt. This receipt includes:
- **SHA-256 hash** of the artifact
- **Byte size** of the rendered output
- `checksPassed` versus `checkCount`
- Composition status fields

The receipt assembly occurs in `archify/bin/archify.mjs` at lines 628-632:

```javascript
const artifact = fs.readFileSync(htmlCandidate);
const receipt = {
  ...compareIr,
  artifact: {
    sha256: createHash('sha256').update(artifact).digest('hex'),
    bytes: artifact.byteLength,
  },
  validation: {
    checksPassed: baseChecks + headChecks + deltaValidation.checksPassed,
    checkCount:   baseResult.checks.checks.length +
                  headResult.checks.checks.length +
                  deltaValidation.checkCount,
    baseComposition: baseResult.checks.composition.status,
    headComposition: headResult.checks.composition.status,
  },
};
fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);

```

## Consuming the Validation Receipt

The receipt serves as the single source of truth across Archify's ecosystem. Scripts can consume it directly:

```javascript
const { validation } = require('./artifact-receipt.json');
if (validation.checksPassed === validation.checkCount &&
    validation.compositionStatus === 'pass') {
  console.log('✅ Artifact is fully validated');
} else {
  console.warn('⚠️ Validation problems detected');
}

```

### CLI Output

When running `archify validate … --json`, success prints only the receipt JSON. Failure produces a single JSON object with diagnostic details—no stack traces pollute the output.

### Gallery and Showcase Integration

The HTML preview embeds the receipt directly. The UI displays a green **"PASS"** badge when `checksPassed === checkCount` and composition status equals `pass`.

### Test Verification

Unit tests assert receipt correctness. The test `archify/test/ordinary-model-floor.test.mjs` verifies validation fields at lines 101-103:

```javascript
// Verifying receipt.gates.validation structure
assert.strictEqual(receipt.gates.validation.checksPassed, 9);
assert.strictEqual(receipt.gates.validation.checkCount, 9);

```

The gallery test in `archify/test/gallery.test.mjs` enforces that every showcased artifact meets the **9/9 checks** requirement.

## Determinism and Integrity Guarantees

Archify's validation pipeline ensures **deterministic reproducibility**:

1. Identical source IR forces a fresh render
2. Fresh render triggers re-validation
3. Re-validation produces a new SHA-256 hash
4. Chain result: identical source → identical artifact hash → identical receipt

This cryptographic linkage prevents stale or tampered artifacts from circulating undetected.

## Key Source Files

| File | Purpose |
|------|---------|
| `archify/renderers/shared/validator.mjs` | Core `validateSchema` function for JSON-IR validation |
| `archify/bin/archify.mjs` | CLI entry; assembles final receipt at lines 628-632 |
| `archify/renderers/dataflow/render-dataflow.mjs` | Renderer-specific composition checks |
| `archify/test/ordinary-model-floor.test.mjs` | Unit test verifying receipt validation fields |
| `archify/test/gallery.test.mjs` | Gallery-wide 9/9 validation gate enforcement |

## Summary

- **Schema validation** checks JSON-IR against AJV schemas with detailed diagnostics
- **Composition validation** inspects geometric layout quality after rendering
- **Receipt synthesis** produces a SHA-256-verified, deterministic validation record
- The receipt drives CLI output, gallery badges, and automated test assertions
- Determinism guarantees emerge from cryptographic chaining of source → artifact → receipt

## Frequently Asked Questions

### What formats can Archify validate?

Archify validates diagram types including workflow, architecture, and data-flow diagrams. Each type has a generated AJV schema in `archify/renderers/shared/validator.mjs` that defines valid JSON-IR structure.

### How does Archify handle validation failures?

Validation failures transform into diagnostic objects containing the subject, evidence, and supported fixes. The CLI prints these as clean JSON without stack traces when using `--json` flag.

### What does the 9/9 checks requirement mean?

The gallery test enforces that every showcased artifact passes all nine validation checks—combining schema and composition validations—ensuring consistent quality for public-facing diagrams.

### Can I validate Archify artifacts programmatically?

Yes. Import `validateSchema` from `archify/renderers/shared/validator.mjs` and parse receipt JSON files to check `validation.checksPassed`, `validation.checkCount`, and `compositionStatus` fields in your own tooling.