How Archify Validation Ensures Atomic Delivery of Artifacts with SHA-256 Checksums

Archify guarantees atomic artifact delivery by validating specifications through nine built-in checks, freezing them upon success, and using SHA-256 checksums to atomically replace files only after full verification passes.

The Archify validation and delivery workflow in tt-a1i/archify enforces a strict, deterministic contract that prevents partial or corrupted artifacts from ever reaching production. Every step—from initial validation through final delivery—is designed around immutability, cryptographic integrity, and atomic filesystem operations.

The Validation Pipeline: Nine Checks Before Any Output

Before any artifact can be delivered, the Archify CLI runs comprehensive validation through bin/archify.mjs. The validate command executes nine built-in artifact checks covering schema compliance, layout correctness, composition rules, and more.

node bin/archify.mjs validate architecture my-diagram.json \
  --quality showcase --json

The validator produces a receipt containing dual SHA-256 hashes: one for the raw specification bytes and another for the rendered artifact preview. This receipt serves as the cryptographic foundation for all subsequent operations.

According to [archify/SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), the validation stage reports both hashes alongside a quality score, ensuring that any modification—intentional or accidental—immediately invalidates the chain of trust.

Freezing Specifications: Immutability After Validation

Once validation passes with zero errors and zero warnings, the specification enters a frozen state. The CLI treats candidate.json as immutable; any edit requires re-validation and generates a new SHA-256 digest.

This freeze mechanism prevents configuration drift between validation and delivery. Since the specification hash is computed on exact byte sequences, even whitespace changes trigger a full re-validation cycle, maintaining strict determinism.

Atomic Delivery: The Rename-Only Commit Pattern

The deliver command implements true atomic replacement through private snapshot files and filesystem rename semantics:

node bin/archify.mjs deliver architecture my-diagram.json output.html \
  --quality showcase --json

The delivery workflow follows four critical steps as documented in [archify/references/delivery-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md):

1. Snapshot Creation — The specification bytes are written to a private same-directory temporary file, isolated from the production artifact path.

2. Render and Re-validate — The snapshot is rendered to HTML, then subjected to the full artifact checker again to catch any environment-dependent discrepancies.

3. Receipt Generation — A final receipt emits both SHA-256 hashes (specification and artifact) plus byte counts for audit trails.

4. Atomic Replace — Only if all checks pass, the CLI performs a filesystem rename to overwrite the previous target. This rename is atomic at the OS level—readers always see either the old or new artifact, never a partially-written state.

If any stage fails—renderer crash, validation warning, receipt error, or rename exception—the process exits non-zero, removes the temporary snapshot, and preserves the prior trusted artifact byte-for-byte.

Deterministic Receipts: Cryptographic Proof of Integrity

Archify's SHA-256 implementation guarantees bit-for-bit reproducibility. The specification hash covers the exact JSON IR bytes; the artifact hash covers the rendered HTML output. Repeated runs with identical inputs produce identical hash pairs, enabling:

• Cache validation — Build systems can skip redundant re-renders when hashes match.
• Supply chain auditing — Third parties can verify that a deployed artifact matches its claimed source.
• Rollback verification — Previous receipts provide immutable checkpoints for disaster recovery.

Real-world receipts appear in scripts/build-gallery.mjs, which generates proof artifacts with embedded SHA-256 hashes for gallery publication.

Safety Guarantees for CI/CD Pipelines

The delivery contract explicitly hardens against failure modes common in automated environments:

• Non-zero exit codes on any validation or delivery failure, stopping dependent pipeline steps.
• Automatic cleanup of temporary snapshots, preventing disk pollution.
• Preservation of existing artifacts when new deliveries fail, maintaining service continuity.

These properties make Archify suitable for unattended agent workflows where human review is unavailable between validation and deployment.

Sample Validation and Delivery Output

// Validation receipt
{
  "specification_sha256": "a1b2c3d4e5f6...",
  "artifact_sha256": "f7e8d9c0b1a2...",
  "validation": "9/9 showcase, 0 errors, 0 warnings"
}

// Delivery receipt (superset of validation)
{
  "specification_sha256": "a1b2c3d4e5f6...",
  "artifact_sha256": "f7e8d9c0b1a2...",
  "validation": "9/9 showcase, 0 errors, 0 warnings",
  "visual_review": "passed",
  "correction_rounds": 0
}

Note that delivery receipts include but do not replace validation receipts—the specification and artifact hashes must match between stages, or delivery aborts.

Preview Mode: Safe Experimentation Without Side Effects

For iterative development, Archify provides a preview command that renders outputs without any atomic replacement or receipt generation:

node bin/archify.mjs preview architecture my-diagram.json preview.html \
  --quality showcase

This allows rapid iteration while maintaining strict separation from production artifacts.

Summary

• Nine built-in checks must pass before any artifact enters the delivery pipeline.
• Dual SHA-256 hashes bind specifications to rendered outputs with cryptographic certainty.
• Frozen specifications prevent drift between validation and delivery phases.
• Atomic rename operations guarantee readers never observe partially-written artifacts.
• Failure handling preserves existing production artifacts and exits with actionable error codes.

Frequently Asked Questions

What happens if the SHA-256 checksums don't match between validation and delivery?

The delivery command aborts with a non-zero exit code, removes the temporary snapshot, and leaves the existing production artifact untouched. This mismatch indicates either specification modification after validation or environment-dependent rendering variance—both require investigation before retry.

Can I verify an artifact's integrity without running the full delivery pipeline?

Yes. The validation receipt contains independent SHA-256 hashes for both the specification and preview artifact. You can re-run validate on the same specification and compare outputs, or compute SHA-256 hashes directly using standard tools against the reported values.

Does Archify support incremental or partial updates to artifacts?

No. The atomic delivery design intentionally prohibits partial updates. Every delivery replaces the entire artifact or fails entirely. This eliminates a class of consistency bugs where dependent resources reference incompletely updated content.

How does Archify handle concurrent delivery attempts to the same target?

The private snapshot pattern with atomic rename provides inherent serialization. While Archify does not implement explicit distributed locking, filesystem rename semantics ensure that concurrent processes produce deterministic outcomes: one succeeds, others fail with appropriate error codes, and no corruption occurs.

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