How the Archify Deliver Command Ensures Atomic Commits of Diagrams

The archify deliver command guarantees atomic diagram commits by staging candidate artifacts in temporary directories, executing full validation suites, and performing atomic filesystem renames only after all checks pass, ensuring users never encounter partially generated or corrupted diagrams.

The archify deliver command in the tt-a1i/archify repository provides a robust mechanism for generating and deploying technical diagrams without risk of exposing intermediate or broken states. By leveraging filesystem-level atomic operations and comprehensive validation gates, the tool ensures that every diagram replacement follows an all-or-nothing commitment pattern. This approach guarantees that observers always see either the previous verified version or a completely validated new version—never a hybrid or failed state.

Staging Strategy: Isolated Temporary Directories

The atomic guarantee begins with strict isolation of the generation process. Rather than writing directly to the target output path, the command creates a uniquely named staging directory using Node.js filesystem APIs.

Creating the Staging Environment

In archify/bin/archify.mjs, the command initializes a temporary workspace using:

stagingDirectory = fs.mkdtempSync(
  path.join(outputDirectory, '.archify-delivery-')
)

This creates a directory prefixed with .archify-delivery- within the output directory, ensuring the candidate artifact remains invisible to consumers until explicitly promoted. The test suite in archify/test/cli.test.mjs verifies that the CLI consistently uses this prefix for all staging operations.

The Validation Gate: All-or-Nothing Verification

Before any filesystem promotion occurs, the candidate diagram undergoes rigorous scrutiny through the same comprehensive validation pipeline used by the standalone validate command.

Pipeline Validation Before Commit

The staging artifact is subjected to checks covering schema compliance, layout integrity, geometry constraints, and perceptual quality gates. As implemented in the source code at archify/bin/archify.mjs, this validation mirrors the full suite described in the repository's documentation for the "Deliver" step. Only when all validation checks pass does the process proceed to the replacement phase. If any check fails, the command aborts the operation entirely, leaving the existing output file untouched.

Atomic Replacement and Failure Handling

The critical atomic guarantee relies on POSIX filesystem semantics and strict cleanup protocols.

Filesystem-Level Atomic Rename

Upon successful validation, the command executes an indivisible rename operation:

fs.renameSync(stagingPath, targetOutputPath)

On POSIX-compliant systems, renaming within the same filesystem is an atomic operation from the operating system's perspective. This means the swap between the old artifact and the new candidate occurs instantaneously—observers never encounter a partially written or truncated file during the transition.

Cleanup on Validation Failure

If validation detects errors, the command immediately removes the staging directory and exits without modifying the target path. The test file archify/test/repair-receipt.test.mjs asserts that no .archify-delivery- prefixed folders survive after a failed or successful delivery run, ensuring failed deliveries leave no stray artifacts that could be mistakenly consumed.

Delivery Receipts and Integrity Verification

Beyond atomic replacement, the command provides cryptographic verification of the delivered artifact.

The JSON receipt returned by the command includes a specification.sha256 field containing the SHA-256 hash of the final diagram file. This allows downstream systems to verify that the atomically committed artifact matches the exact bytes validated during the delivery process, providing an additional layer of reproducibility and tamper detection.

Practical Usage Example

Execute the atomic delivery workflow using the CLI:

node archify/bin/archify.mjs deliver workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase \
  --open \
  --json

When the command exits with status 0, the JSON receipt confirms the atomic commit succeeded. Any non-zero exit status indicates the previous diagram remains unchanged and no partial writes occurred.

Summary

• Isolation via staging: The command creates .archify-delivery- prefixed temporary directories to hide incomplete artifacts from consumers.
• Validation gate: Full schema, layout, and geometry checks must pass before promotion, ensuring only verified diagrams reach the target path.
• Atomic replacement: The fs.renameSync operation provides filesystem-level atomicity, preventing exposure of partial files during updates.
• Automatic cleanup: Failed deliveries remove temporary directories immediately, leaving no stray files according to test assertions in archify/test/repair-receipt.test.mjs.
• Integrity tracking: Delivery receipts include SHA-256 hashes for reproducibility verification.

Frequently Asked Questions

What happens if validation fails during an Archify deliver command execution?

If any validation check fails—whether schema validation, layout verification, or geometry constraints—the command immediately discards the staging directory and exits without modifying the existing output file. This ensures the target path retains only the previously verified artifact, and the test suite confirms that no .archify-delivery- temporary folders remain after such failures.

How does the atomic rename in Archify ensure data integrity?

The command uses fs.renameSync to move the validated candidate from the staging directory to the target output path in a single operation. On POSIX systems, this rename is atomic at the kernel level, meaning observers always see either the complete old file or the complete new file, never a partially written state or corrupted intermediate version.

Where does Archify store temporary files during the deliver process?

Temporary artifacts are stored in directories created by fs.mkdtempSync with the prefix .archify-delivery-, located within the specified output directory. This approach keeps intermediate files co-located with the final destination while maintaining invisibility until the atomic promotion occurs.

How can I verify the integrity of a diagram after atomic delivery?

The JSON receipt returned by the deliver command includes a specification.sha256 field containing the SHA-256 hash of the final artifact. You can compare this hash against a local computation of the output file to confirm that the delivered diagram matches exactly what was validated during the atomic commit process.

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