How Archify Validation and Delivery Commands Ensure Artifact Quality

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:

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

# Outputs: schemaErrors, profile, and diagnostics array

Deliver an architecture diagram with strict quality checks:

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:

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.

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