Archify Delivery Contract and Atomic Commit Behavior Explained

The Archify delivery contract is a three-phase pipeline—validate and render, deterministic receipt generation, and atomic commit—that guarantees HTML artifacts are only published after passing all validation, rendering, and artifact-checking steps.

The Archify delivery contract governs how the tt-a1i/archify tool transforms JSON specifications into trusted HTML artifacts. This contract ensures that no corrupted, partially rendered, or invalid output ever replaces an existing trusted artifact, using filesystem-level atomic operations to enforce safety.

What the Archify Delivery Contract Specifies

The contract defines three sequential phases that every delivery must complete:

• Validate and render – The JSON specification is parsed, validated against its schema, and rendered to a temporary candidate file.
• Deterministic receipt – A receipt containing SHA-256 hashes and byte counts for both the original specification and the rendered artifact is generated.
• Atomic commit – Only when the receipt passes all artifact-checking steps does Archify perform a filesystem rename from candidate to final output.

This structure guarantees that failure at any stage leaves the existing output untouched. The contract is documented in archify/references/delivery-contract.md and implemented in archify/bin/archify.mjs.

How Atomic Commit Works in the Source Code

The atomic commit mechanism centers on the commandDeliver function in archify/bin/archify.mjs. The implementation follows a strict ordering that makes failure modes safe by design.

Staging Directory Creation

Archify creates a staging folder adjacent to the target output path. This placement ensures the final rename is a single atomic filesystem operation on the same device.

// Keep the candidate beside the target so the final rename is one
// same-filesystem commit. A render or artifact-check failure never touches
// an existing trusted output.
const stagingDirectory = fs.mkdtempSync(path.join(outputDirectory, '.archify-delivery-'));

Lines 40-44 of archify.mjs establish this invariant. If the staging directory cannot be created, the delivery aborts immediately.

Specification Freezing and Candidate Rendering

The tool writes an immutable snapshot of the specification using the wx flag (lines 70-73):

// specification.snapshot.json written with 'wx' — fails if exists
fs.writeFileSync(snapshotPath, JSON.stringify(specification, null, 2), { flag: 'wx' });

The renderer then produces the candidate HTML. If rendering fails, reportDeliveryFailure is invoked and the function returns before any filesystem state changes (lines 95-108).

Artifact Checking and Receipt Parsing

The artifact checker (archify/scripts/check-render-output.mjs) validates the candidate against nine composition and quality checks. Failure here likewise triggers early abort (lines 122-134).

The checker writes a receipt that commandDeliver must parse successfully. Invalid receipt syntax prevents delivery (lines 140-155):

const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
if (!receipt.ok) {
  return reportDeliveryFailure('Artifact checks failed', receipt);
}

The Atomic Rename Operation

Only after all prior steps succeed does Archify execute the critical operation (lines 61-63):

fs.renameSync(candidatePath, outputPath);

Because candidatePath and outputPath reside on the same filesystem, this rename is atomic—observers see either the old file or the new file, never a partial write or corrupted intermediate state.

Cleanup and Optional Preview

A finally block (lines 9-13) removes the staging directory regardless of success or failure. The optional --open flag triggers only after the rename completes (lines 82-96), ensuring that preview failures cannot corrupt the published artifact.

Receipt Format and Traceability

The delivery contract mandates a deterministic receipt that enables byte-level auditing. A typical receipt structure:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "deliver",
  "type": "architecture",
  "output": "/abs/path/output.html",
  "specification": { "sha256": "c1a2…", "bytes": 1234 },
  "artifact":      { "sha256": "d4e5…", "bytes": 5678 },
  "validation": {
    "checksPassed": 9,
    "checkCount": 9,
    "compositionProfile": "showcase",
    "compositionStatus": "passed"
  }
}

The specification_sha256 and artifact_sha256 fields provide cryptographic proof of identity. The checksPassed and checkCount fields demonstrate that all validation rules were satisfied before commit.

Practical Delivery Commands

Standard Delivery with Contract Enforcement

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

This executes the full pipeline: validation, rendering, artifact checking, receipt generation, and atomic rename. The --json flag outputs the receipt for programmatic inspection.

Delivery with Post-Commit Preview

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

The --open flag invokes archify/open-artifact.mjs only after the atomic rename succeeds. Preview failures are isolated from delivery success.

Key Files in the Atomic Commit Implementation

Path	Role
archify/references/delivery-contract.md	Human-readable specification of the delivery pipeline, receipt format, and safety guarantees.
archify/bin/archify.mjs	CLI implementation; commandDeliver function enforces the atomic commit workflow.
archify/scripts/check-render-output.mjs	Artifact checker that produces the deterministic receipt required for commit.
archify/renderers/shared/output-path.mjs	Output path resolution ensuring staging and target locations share a filesystem.
archify/open-artifact.mjs	Post-commit preview handler; never influences delivery outcome.

Summary

• The Archify delivery contract is a three-phase pipeline (validate/render, receipt generation, atomic commit) that prevents partial or failed deliveries from corrupting published artifacts.
• Atomic commit is implemented via same-filesystem staging and fs.renameSync, guaranteeing that observers see either the old or new file, never an intermediate state.
• Receipts provide cryptographic traceability through SHA-256 hashes of both specification and artifact, plus validation metadata.
• The --open preview runs strictly after commit, isolating UI failures from delivery integrity.
• All safety logic resides in archify/bin/archify.mjs with the contract documented at archify/references/delivery-contract.md.

Frequently Asked Questions

What happens if the artifact checker fails during delivery?

Archify aborts immediately and leaves the existing output unchanged. The reportDeliveryFailure function is invoked (lines 95-108, 122-134 of archify.mjs), the staging directory is cleaned up in the finally block, and the atomic rename never executes.

Why does Archify use fs.renameSync instead of a copy operation?

fs.renameSync on the same filesystem is atomic—no observer can see a partially written file. A copy operation would risk exposing incomplete data if interrupted. The staging directory placement adjacent to the target ensures this atomicity guarantee.

Can I verify that a delivered artifact matches its specification?

Yes. The receipt contains specification.sha256 and artifact.sha256 fields that cryptographically bind the input JSON to the output HTML. Recalculate these hashes to verify integrity or audit historical deliveries.

Does the --open flag affect delivery success?

No. The optional preview implemented in archify/open-artifact.mjs executes only after the atomic rename completes (lines 82-96). Preview failures are logged but do not alter the delivery status or the committed artifact.

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