Archify Artifact Check Validation Explained: The Three-Stage Pipeline

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:

// 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:

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:

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:

// 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}