How Archify Ensures Atomic Commits in Its Delivery Workflow

Archify guarantees atomic commits through a single-write, immutable-artifact contract that only publishes deliveries after full verification, with automatic cleanup on any failure.

The tt-a1i/archify repository implements a delivery pipeline designed around transactional semantics. Every code delivery follows a strict protocol: generate a deterministic artifact in temporary isolation, verify it against quality gates, and promote it only when all checks pass. This article breaks down the exact mechanisms that make Archify's delivery workflow atomic.

The Atomic Delivery Contract

Archify's delivery workflow enforces four core principles that together create atomic commit semantics:

• Deterministic artifact generation — Each delivery produces byte-identical output given identical input
• Pre-publication verification — All quality gates must pass before any state change occurs
• Automatic rollback on failure — Temporary artifacts are discarded, leaving the repository unchanged
• Idempotent execution — Repeated runs produce the same SHA-256 digest, preventing drift

These principles are codified in docs/deployment-ownership-profile-acceptance-2026-07-23.md, which documents that "repeated delivery of the same source produces the same HTML SHA-256" and that failed profile deliveries preserve previous artifact bytes.

Stage 1: Temporary Artifact Generation

The delivery workflow begins by creating an isolated workspace. In scripts/build-gallery.mjs, the workflow definition declares id: 'delivery-workflow' (line 60) and specifies its JSON input configuration.

When executed, the delivery script writes all output to a temporary directory prefixed with .archify-delivery-*. This naming convention serves two purposes: it prevents collisions between concurrent deliveries and makes cleanup straightforward.

The generation process is deterministic by design. The script hashes the output bytes to produce a canonical digest, binding the artifact to its exact contents.

// Conceptual flow from archify/test/preview.test.mjs
const delivery = async (inputPath) => {
  const tmp = await fs.mkdtemp('.archify-delivery-');
  const artifact = await runDeliveryScript(inputPath, tmp);
  const digest = sha256(await fs.readFile(artifact));
  // ... verification before any promotion
};

Stage 2: Delivery Receipt Verification

Before any artifact becomes visible downstream, Archify runs a suite of delivery receipts — automated tests that verify correctness, schema compliance, and policy adherence.

Receipt Test 1: Cleanup Verification

archify/test/repair-receipt.test.mjs executes a simulated delivery and confirms that failed runs leave no residue. The critical assertion on line 128 validates atomic cleanup:

assert.deepEqual(
  fs.readdirSync(tmp).filter((name) => name.startsWith('.archify-delivery-')),
  []
);

This test ensures that temporary directories are always removed, even when deliveries fail mid-process.

Receipt Test 2: Immutable Digest Validation

archify/test/preview.test.mjs verifies that deliveries read exactly the bytes they hash. Line 302 contains the validation marker:

assert.ok(fs.existsSync(readMarker), 'fake delivery never read its generation input');

This prevents a class of bugs where a delivery might hash one version of input but read another during actual processing.

Stage 3: Atomic Promotion or Rollback

The final stage embodies the all-or-nothing guarantee. The workflow evaluates all receipt results:

Outcome	Action	Repository State
All gates pass	Atomic rename from temp to final location	New artifact visible
Any gate fails	Recursive deletion of temp directory	No change — previous artifact preserved

This mirrors database transaction semantics: the temporary directory acts as a staging area that either commits entirely or aborts completely.

The rollback safety is explicitly documented in docs/gallery/artifacts/release-delivery.workflow.html. The HTML artifact — itself only published after successful verification — contains a <script id="archify-guided-views-data"> block (lines 4504-4523) mapping out the commit-to-checks, approval-to-production, and rollback paths.

Idempotency Prevents Drift

Atomicity would be undermined if the same source could produce different artifacts on subsequent runs. Archify prevents this through deterministic build processes that yield identical SHA-256 hashes for identical inputs.

The deployment-ownership-profile-acceptance documentation explicitly tests this property. This ensures that once a delivery successfully commits, developers can trust that reproducing that delivery from the same source will yield bit-for-bit identical results.

Summary

• Temporary isolation: All delivery work happens in .archify-delivery-* directories, invisible to consumers until promotion
• Verification-before-promotion: repair-receipt.test.mjs and preview.test.mjs enforce correctness before any state change
• Automatic cleanup: Failed deliveries guaranteed to leave no artifacts behind via fs.rm(tmp, { recursive: true })-equivalent cleanup
• Immutable identity: SHA-256 digests bind artifacts to exact byte contents, preventing silent drift
• Explicit rollback paths: The workflow definition in release-delivery.workflow.html documents safe reversal points

Frequently Asked Questions

What happens if a delivery receipt fails halfway through?

The temporary .archify-delivery-* directory is deleted and the repository remains unchanged. As verified by archify/test/repair-receipt.test.mjs, no stray delivery artifacts survive a failed run — this is the core of the atomic guarantee.

How does Archify prevent concurrent deliveries from interfering?

Each delivery receives its own uniquely-named temporary directory via fs.mkdtemp('.archify-delivery-'). Only after successful verification does the workflow perform an atomic filesystem rename to the final location, which is an OS-level atomic operation.

Why does Archify use SHA-256 instead of simpler checksums?

SHA-256 provides collision resistance and determinism sufficient for content-addressed storage. The digest serves as the canonical identity of a delivery, enabling reliable caching, verification, and audit trails. As documented in the deployment acceptance criteria, identical inputs must produce identical digests.

Can I inspect the delivery workflow without running it?

Yes. The fully rendered workflow is available in docs/gallery/artifacts/release-delivery.workflow.html, which includes the guided views data showing all quality gates and rollback paths. This artifact is itself produced by the delivery pipeline, demonstrating the system eating its own dog food.

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