How the Archify Delivery Workflow Ensures Artifact Integrity

Archify guarantees artifact integrity through an atomic verified delivery pipeline that combines read-once specifications, isolated staging, comprehensive validation, cryptographic receipts, and atomic file commits.

The tt-a1i/archify repository implements a deterministic build pipeline designed to prevent tampering and ensure that every generated artifact exactly matches its source specification. By treating delivery as a transactional operation with cryptographic verification, the workflow creates tamper-evident proof of integrity that downstream systems can validate independently.

The Atomic Verified Delivery Model

At the core of Archify’s delivery workflow lies an atomic verified delivery model defined in archify/references/delivery-contract.md. This model treats artifact generation as a gated transaction where the target file is only mutated after passing a complete validation suite. The architecture ensures that either the entire operation succeeds atomically, leaving a cryptographically signed receipt, or fails completely without touching existing artifacts.

The implementation resides primarily in archify/cli.mjs, where the deliver command orchestrates the six-stage integrity pipeline.

Six-Step Integrity Assurance Process

1. Read-Once Specification Capture

The delivery process begins with immutable input handling. The deliver command reads the input JSON specification exactly once and immediately writes those bytes to a private candidate snapshot in the same directory.

This read-once semantics prevents race conditions where the source file might change between validation and rendering. As specified in the delivery contract, the system captures the exact byte stream that will drive the entire pipeline, ensuring deterministic reproducibility.

2. Isolated Staging Environment

Archify renders the candidate artifact inside a dedicated staging folder rather than the final destination. This isolation prevents external processes from modifying the output during generation. The staging directory acts as a quarantine zone where the artifact remains mutable until it passes all quality gates.

No external file system access occurs during the render phase, eliminating contamination risks from concurrent operations or environment changes.

3. Comprehensive Artifact Validation

Before any commit occurs, Archify executes its exhaustive artifact checker against the staged output. This checker runs graph-structure validation, composition analysis, and visual-quality checks defined in the test suite.

According to archify/references/delivery-contract.md, the pipeline only proceeds when all checks pass. Any failure triggers an immediate abort, leaving the previously trusted artifact untouched and deleting the candidate directory. This fail-fast behavior ensures that only validated artifacts reach the publication stage.

4. Cryptographic Receipt Generation

Upon successful validation, Archify generates a deterministic JSON receipt that serves as tamper-evident proof of integrity. The receipt, assembled in logic similar to scripts/build-gallery.mjs, includes:

• SHA-256 digests of both the specification and final artifact
• Byte counts for both files
• A complete list of passed and failed checks
• Stage-by-stage execution status

This receipt is written atomically alongside the artifact, creating a permanent record that CI systems, agents, or downstream tools can consume to verify that the artifact matches the source exactly.

5. Atomic Commit Operation

The final publication step uses a single rename operation to replace the target file with the validated staging artifact. Because the rename is the only mutation point, the system guarantees that the published file is exactly the one that passed all checks and matches the receipt’s SHA-256 hash.

As documented in archify/SKILL.md, if any preceding step fails, the candidate directory is discarded and the previous artifact remains completely untouched. This atomic semantics prevents partial or corrupted updates from reaching production.

6. Deterministic Reproducibility

The workflow ensures byte-for-byte reproducibility when re-executed with identical inputs. The test suite in archify/test/delivery-contract.test.mjs explicitly verifies that re-running delivery with the same source bytes yields identical SHA-256 digests for both the specification and artifact.

This property allows teams to independently verify builds and confirms that the pipeline contains no non-deterministic transformations that could compromise integrity.

Verifying Integrity Programmatically

You can invoke the delivery workflow and inspect the resulting receipt using the archify deliver command:

# Generate and publish a diagram atomically with JSON receipt output

archify deliver workflow docs/gallery/sources/release-delivery.workflow.json docs/gallery/artifacts/release-delivery.workflow.html --json

The command outputs a machine-readable receipt:

{
  "ok": true,
  "specificationSha256": "a3f1e2…",
  "artifactSha256": "c41965605d4b7157c8a080aa52cf7d10…",
  "specificationBytes": 2743,
  "artifactBytes": 12345,
  "checksPassed": 9,
  "checksTotal": 9,
  "stages": [{"name":"read","ok":true}, {"name":"render","ok":true}, {"name":"check","ok":true}, {"name":"commit","ok":true}]
}

Downstream validation scripts can verify integrity by comparing the receipt against expected hashes:

const fs = require('fs');
const receipt = JSON.parse(fs.readFileSync('receipt.json'));
const expectedSha256 = process.env.EXPECTED_ARTIFACT_HASH;

if (receipt.ok && receipt.artifactSha256 === expectedSha256) {
  console.log('Artifact integrity confirmed: matches specification and passed all checks');
  process.exit(0);
} else {
  console.error('Integrity check failed: artifact mismatch or validation error');
  process.exit(1);
}

Summary

• Read-once semantics in archify/cli.mjs prevent specification tampering during the delivery pipeline.
• Isolated staging ensures external processes cannot modify artifacts during render.
• Full validation suite must pass before any commit occurs, preventing defective artifacts from publication.
• Cryptographic receipts containing SHA-256 hashes and byte counts provide tamper-evident proof of integrity.
• Atomic rename operations guarantee that target files are either fully updated to the validated artifact or remain completely untouched.
• Deterministic reproducibility verified in archify/test/delivery-contract.test.mjs ensures identical inputs produce identical outputs.

Frequently Asked Questions

How does Archify prevent partial or corrupted artifact updates?

Archify uses an atomic rename operation as the sole mutation point for target files. The validated artifact remains in an isolated staging directory until all checks pass, at which point a single file-system rename replaces the old artifact. If any validation step fails, the staging directory is deleted and the previous artifact remains untouched, ensuring no partial writes ever reach the destination.

What cryptographic guarantees does the delivery receipt provide?

The JSON receipt generated by the delivery workflow includes SHA-256 digests of both the source specification and the final artifact, along with exact byte counts. These hashes allow downstream systems to cryptographically verify that the artifact matches the specification exactly and has not been modified post-delivery. The receipt format is defined in archify/references/delivery-contract.md and implemented in scripts/build-gallery.mjs.

Can the delivery workflow be integrated into CI/CD pipelines?

Yes. The archify deliver command supports --json output for machine-readable receipts, and its exit codes reflect success or failure of the integrity checks. CI systems can parse the receipt to verify artifact hashes match expected values, and the atomic commit semantics ensure that parallel jobs cannot publish conflicting versions of the same artifact.

How does Archify ensure reproducible builds across different environments?

The workflow enforces deterministic rendering where the same input bytes always produce the same output bytes and identical SHA-256 hashes. This is explicitly tested in archify/test/delivery-contract.test.mjs, which verifies that repeated deliveries of identical specifications yield matching digests, confirming that the pipeline contains no environment-specific or time-based variations that could compromise integrity verification.

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