Archify Delivery Workflow with Receipts: A Complete Guide

Archify's delivery workflow is a deterministic four-stage pipeline that produces machine-readable receipts to guarantee only validated, reproducible HTML artifacts are published.

The tt-a1i/archify repository implements a strict delivery contract that transforms JSON intermediate representation (IR) into verified diagrams. Every delivery generates a cryptographically signed receipt recording validation checks, artifact metrics, and SHA-256 hashes, ensuring atomic replacement of artifacts only when all quality gates pass.

The Four-Stage Delivery Pipeline

Archify processes diagrams through a deterministic pipeline that separates generation from validation and delivery. Each stage builds upon the previous, with the receipt acting as the single source of truth for artifact integrity.

1. Generate

An agent (such as Raven, Cursor, or Claude Code) creates a typed JSON IR describing the architecture or workflow. This source file contains the complete specification of nodes, edges, and layout rules, but contains no rendered output.

2. Validate

Built-in validators in archify/bin/archify.mjs execute against the JSON IR:

• Schema validation: Ensures the IR conforms to the expected type structure
• Layout rules: Verifies orthogonal arrows and finite SVG boundaries
• Legend clearance: Confirms legends do not overlap diagram elements
• Deterministic hashing: Computes a SHA-256 hash of the expected artifact

These checks populate the receipt fields: schema, layout, finite_svg, legend_clearance, and artifactSha256.

3. Preview (Optional)

The preview mode watches the source file for changes and reloads only after passing validation. This desktop loop keeps the last-good artifact visible while invalid changes are being edited, preventing broken diagrams from entering the delivery stage.

4. Deliver

The delivery stage renders the validated source to HTML (or PNG/SVG/WebM). Located in archify/bin/archify.mjs, the delivery program writes a receipt JSON containing validation results, artifact metrics, and the final SHA-256 hash. According to the logic in scripts/package-smoke.mjs, the CLI throws an error if the receipt indicates any failure:

throw new Error('packaged workflow delivery did not return a passing receipt');

Anatomy of a Delivery Receipt

The receipt is a machine-readable JSON file produced alongside the artifact. A typical receipt contains the exact checks that were run, the metrics of the rendered artifact, and whether the delivery succeeded.

Running the delivery command produces output like this:

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

The resulting receipt structure follows this schema:

{
  "receipt": "12 nodes · 11 edges · 9/9 checks",
  "checksPassed": 9,
  "checkCount": 9,
  "composition": {
    "status": "pass",
    "profile": "showcase"
  },
  "nodeCount": 12,
  "edgeCount": 11,
  "artifactSha256": "a1b2c3d4e5f6..."
}

Key fields include:

• checksPassed/checkCount: The ratio of successful validation checks
• composition.status: Either "pass" or "fail" indicating overall validity
• artifactSha256: The 64-character SHA-256 hash of the generated HTML file

Atomic Replacement Guarantee

The receipt acts as an atomic gate for artifact publication. The HTML file is written only when checksPassed === checkCount, ensuring that every published diagram is reproducible and auditable.

This mechanism prevents partial or corrupted deliveries. As implemented in scripts/package-smoke.mjs, the delivery workflow validates the receipt before considering the operation successful. If any check fails, the previous artifact remains in place, maintaining the integrity of the documentation gallery.

Running the Delivery Command

To execute the delivery workflow and generate a receipt, use the CLI entry point at archify/bin/archify.mjs:

# Generate the receipt while delivering the workflow

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

This command:

1. Validates the source JSON against schema and layout rules
2. Renders the HTML artifact
3. Computes the SHA-256 hash
4. Writes both my-workflow.html and its accompanying receipt

Programmatic Receipt Validation

Downstream consumers can verify deliveries without re-running the entire pipeline by inspecting the receipt file:

const receipt = JSON.parse(
  fs.readFileSync('my-workflow.html.receipt.json', 'utf8')
);

if (receipt.checksPassed !== receipt.checkCount) {
  throw new Error('Delivery failed – see receipt for details');
}
console.log('Delivery succeeded! SHA‑256:', receipt.artifactSha256);

For automated testing, assert against specific receipt fields:

import assert from 'assert';
import receipt from '../my-workflow.html.receipt.json';

assert.equal(receipt.checksPassed, receipt.checkCount);
assert.ok(receipt.artifactSha256.length === 64);

The archify/SKILL.md file defines the complete receipt schema and delivery contract, while docs/gallery/artifacts/ contains real-world examples of delivered HTML files with their corresponding receipts.

Summary

• Archify's delivery workflow consists of Generate, Validate, Preview, and Deliver stages
• The receipt is a JSON file recording validation checks, metrics, and SHA-256 hashes
• Atomic replacement occurs only when checksPassed equals checkCount
• Programmatic validation allows downstream tools to verify artifacts without re-running validators
• Key files include archify/bin/archify.mjs (CLI), archify/SKILL.md (schema), and scripts/package-smoke.mjs (CI validation)

Frequently Asked Questions

What happens if validation fails during delivery?

If any check fails during the delivery stage, the CLI throws an error and the artifact file is not replaced. As seen in scripts/package-smoke.mjs, the workflow ensures that only receipts with checksPassed === checkCount authorize artifact publication, preventing invalid diagrams from entering the gallery.

Where is the receipt stored after delivery?

The receipt is written alongside the output artifact with a .receipt.json extension. For example, delivering to ./my-workflow.html produces ./my-workflow.html.receipt.json in the same directory, making it easy for CI systems to locate and validate.

Can I verify a delivered artifact without re-running the pipeline?

Yes. The receipt contains the artifactSha256 field, which is the SHA-256 hash of the generated HTML file. Consumers can compute the hash of the artifact locally and compare it against the receipt value to verify integrity without executing the validation suite.

What checks are recorded in the receipt?

The receipt records schema validation, layout rules (orthogonal arrows, finite SVG, legend clearance), and composition status. Specific fields include schema, layout, finite_svg, legend_clearance, and composition.status, providing a complete audit trail of the validation process.

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