Archify Deliver Command: Atomic Commit and Receipt Generation Explained

The archify deliver command guarantees atomic file updates by validating artifacts before swapping them into place and emits a cryptographic receipt proving the transaction.

Archify is a Node.js-based diagram generation tool that converts typed JSON specifications into deterministic HTML and SVG visualizations. The deliver command in tt-a1i/archify implements a strict render → validate → deliver workflow that ensures only fully-verified artifacts ever replace existing files, accompanied by machine-readable receipts that serve as immutable proof of validation.

How the Archify Deliver Command Implements Atomic Commit

The atomic delivery mechanism prevents corrupted or invalid artifacts from ever reaching production. In archify/bin/archify.mjs, the commandDeliver function orchestrates this process through a two-phase commit strategy.

The atomic write sequence works as follows:

1. Candidate Generation – The renderer writes the new artifact to a temporary file adjacent to the target path (e.g., web-app.html.tmp)
2. Validation Gate – scripts/check-render-output.mjs runs composition checks (label clearance, route rhythm, etc.) via checkerDiagnostics
3. Atomic Swap – Only upon passing all checks does the tool rename the candidate into place, replacing the existing file in a single filesystem operation
4. Receipt Emission – A JSON receipt containing SHA-256 hashes and validation metadata is printed to stdout

If any validation step fails, the candidate file is discarded and the existing artifact remains untouched. This pattern is also used in commitComparePair for delta comparisons, ensuring that three-panel diff views are only published after successful validation of both base and head snapshots.

Machine-Readable Receipt Structure and Verification

Every successful delivery produces a receipt that serves as cryptographic evidence of the transaction. The receipt format is defined in archify/README.md and archify/SKILL.md, implemented in the delivery logic at lines 105-112 of archify/bin/archify.mjs.

A standard receipt contains:

• Specification Hash – SHA-256 of the source JSON IR and byte count
• Artifact Hash – SHA-256 of the generated HTML/SVG output
• Validation Summary – Checks passed versus total (e.g., 42/45), composition profile (e.g., "signal-flow"), and pass status
• Source Evidence – When the artifact contains <script id="archify-source-evidence-data"> markers, sourceEvidenceFromArtifact extracts repository URL, revision SHA, and reference counts

This receipt enables downstream CI/CD pipelines to verify that deployed diagrams match approved specifications exactly, without re-running the full rendering pipeline.

Practical Usage Examples

Basic Delivery with Receipt

Generate an architecture diagram and atomically commit it with a validation receipt:

npx archify.mjs deliver architecture examples/web-app.json web-app.html --json --open

Resulting receipt structure:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "deliver",
  "type": "architecture",
  "input": "/path/to/examples/web-app.json",
  "output": "/path/to/web-app.html",
  "specification": { "sha256": "…", "bytes": 1234 },
  "artifact": { "sha256": "…", "bytes": 5678 },
  "validation": {
    "checksPassed": 42,
    "checkCount": 45,
    "compositionProfile": "signal‑flow",
    "compositionStatus": "pass"
  },
  "evidence": {
    "verified": true,
    "repository": "https://github.com/example/repo",
    "revision": "a1b2c3d",
    "references": 3
  }
}

Atomic Comparison with Commit

Produce a delta view between architecture versions with dual validation:

npx archify.mjs compare architecture base.json head.json delta.html --receipt delta.receipt.json --json

This creates both delta.html (a three-panel comparison view) and delta.receipt.json containing semantic hashes for both snapshots and a combined validation summary.

Validation and Renderer Isolation

Before any atomic commit occurs, Archify isolates the rendering process to prevent environment pollution. The runNode function spawns the actual diagram generation (rendererPath('architecture'), etc.) in a minimal child process environment (rendererEnv).

Error handling follows strict boundaries:

• Renderer Failures – Captured as structured rendererFailure diagnostics without writing partial output
• Composition Checks – Performed by scripts/check-render-output.mjs after rendering but before the atomic rename
• Quality Profiles – The --quality flag (standard or showcase) sets ARCHIFY_QUALITY_PROFILE to toggle visual presets without affecting validation logic

This architecture ensures that validation errors never corrupt the existing production artifact, maintaining system stability even when rendering edge cases or malformed input JSON.

Summary

• Atomic Delivery – commandDeliver in archify/bin/archify.mjs uses a candidate-file-and-rename pattern to guarantee all-or-nothing updates
• Cryptographic Receipts – Every delivery emits JSON containing SHA-256 hashes, validation metrics, and optional source evidence for audit trails
• Validation Gates – scripts/check-render-output.mjs runs composition checks before any file swap occurs
• Process Isolation – Rendering occurs in sanitized child processes (rendererEnv) to contain failures
• Delta Support – The same atomic semantics apply to commitComparePair for architecture diff generation

Frequently Asked Questions

What happens if validation fails during the deliver command?

If scripts/check-render-output.mjs detects composition errors or the renderer returns a non-zero exit code, commandDeliver discards the candidate file and exits without modifying the target path. The existing artifact remains intact, and the CLI returns structured error diagnostics instead of a receipt.

How does the receipt provide cryptographic proof of delivery?

The receipt includes SHA-256 hashes of both the input specification and final artifact bytes, generated after validation but before the atomic rename. Because the hash captures the exact content that passed validation, any subsequent modification to the file would invalidate the receipt signature, enabling third-party verification of the delivered artifact's integrity.

Can I use atomic delivery for comparing architecture versions?

Yes. The compare sub-command uses commitComparePair (lines 84-111 in archify/bin/archify.mjs) to apply the same atomic semantics to three-panel diff generation. It validates both base and head snapshots before writing the comparison view, ensuring that delta.html only contains successfully rendered comparisons.

Where is the atomic commit logic implemented?

The core atomic delivery logic resides in archify/bin/archify.mjs within the commandDeliver function (lines 84-111). This module coordinates the renderer environment, validation checks via runNode, and the final filesystem operations that commit the validated candidate to its target location.

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