How Archify Handles Failures During the Delivery Process: Atomic Validation and Repair Receipts

Archify prevents broken artifacts from reaching production by enforcing an atomic validation‑before‑delivery pipeline that returns structured repair receipts on failure, ensuring the previous valid version remains live while the user receives actionable diagnostic data.

The open‑source diagram generator tt‑a1i/archify implements a defensive delivery pipeline designed to handle failures during the delivery process without corrupting the live workspace. Instead of overwriting existing artifacts with partially generated or invalid output, the system validates every aspect of the diagram—from JSON IR syntax to route clearance—before committing any bytes to disk.

The Atomic Validation‑Before‑Delivery Model

Archify’s core safeguard is its atomic‑validation‑before‑delivery architecture. Before an HTML, SVG, or WebM artifact is written, the system executes a bundled validation suite that inspects:

• Typed JSON IR consistency
• Layout rule compliance
• SVG generation integrity
• Route clearance validity
• Label‑to‑route mapping accuracy

If any validator reports an error, the delivery aborts completely. This guarantees that the existing live artifact remains untouched and visible to end users, while the broken build is isolated in a temporary .archify-delivery-* directory that is subsequently cleaned up.

Structured Repair Receipts for Programmatic Recovery

When validation fails, Archify does not emit raw stack traces. Instead, it returns a repair receipt containing:

• A stable rule code identifying the violated constraint
• The exact subject of the failure (e.g., specific node or edge)
• Measured evidence detailing how the rule was breached
• A limited set of supported repair controls guiding remediation

These receipts are produced identically by both validate --json and deliver --json, allowing CI/CD pipelines and editor integrations to react programmatically to failures.

CLI Usage and Failure Scenarios

The archify/bin/archify.mjs entry point orchestrates the validation and delivery phases. Below are the exact commands used to detect and handle delivery failures:

# Verify diagram integrity without publishing

node archify/bin/archify.mjs validate --json diagram.json

# Exits 0 on success

# On failure: prints JSON repair receipt and exits non‑zero

# Attempt atomic delivery

node archify/bin/archify.mjs deliver --json diagram.json

# Success: writes artifact to disk and promotes it to live

# Failure: emits repair receipt, preserves previous artifact bytes

According to the test suite in archify/test/repair-receipt.test.mjs, a failed delivery leaves the .archify-delivery-* temporary directory empty and guarantees that the previous artifact’s bytes remain unchanged on disk.

Preview Loop Resilience

For iterative development, the archify preview command provides a preview loop that watches the source JSON file. The loop implements a "reload only on success" policy:

• After each file change, Archify runs the full validation suite.
• If validation passes, the preview refreshes with the new artifact.
• If validation fails, the last‑good artifact stays on screen, ensuring the user never views a broken or partially rendered diagram.

This behavior is documented in the repository README and reinforced by the delivery contract specified in archify/references/delivery-contract.md, which formalizes the distinction between successful publication and failure states.

Summary

• Archify handles failures during the delivery process through atomic validation, ensuring broken artifacts never overwrite live versions.
• Repair receipts provide stable rule codes and measured evidence instead of raw errors, enabling automated remediation workflows.
• The CLI commands validate --json and deliver --json emit identical receipt formats for consistent error handling in pipelines.
• The preview loop preserves the last‑good artifact during editing sessions, preventing broken views while developers fix validation errors.
• Tests in repair-receipt.test.mjs verify that temporary directories are cleaned and previous artifacts remain immutable after failed deliveries.

Frequently Asked Questions

What happens to the live artifact when a delivery fails?

The live artifact remains completely untouched. Because Archify uses an atomic delivery model, the new version is only promoted to live status after all validators pass. If any check fails, the system discards the temporary build and leaves the existing artifact bytes unchanged, ensuring zero downtime or broken views.

How can I programmatically detect what failed during delivery?

Parse the structured repair receipt output by the deliver --json command. This JSON object contains a stable rule code, the exact subject (node or edge) that violated constraints, and measured evidence describing the breach. You can script against these receipts to automate fixes or trigger CI notifications.

Does the preview command show errors in the browser?

No. The archify preview loop intentionally withholds broken renders from the browser. When validation fails, the preview continues displaying the last successful artifact while logging the repair receipt to the console. This ensures designers always see a valid diagram even while the source JSON contains errors.

Where is the failure handling behavior tested?

The primary test coverage resides in archify/test/repair-receipt.test.mjs, which asserts that failed deliveries do not publish artifacts and that repair receipts contain the expected schema. Additional guarantees are documented in archify/references/delivery-contract.md, which defines the formal contract for successful delivery states and failure receipt shapes.

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