The Five Deterministic Stages of the Archify System Pipeline Explained

The Archify system pipeline processes every artifact through five strictly ordered, deterministic stages—Ingest, Validate, Compose, Deliver, and Preview—that guarantee reproducible, auditable results through immutable data flow.

The tt-a1i/archify repository implements a strictly deterministic build pipeline that ensures every input produces identical, verifiable outputs. Understanding the five deterministic stages of the Archify system pipeline is essential for developers who need reproducible artifact generation and atomic deployment guarantees. Each stage features a single, well-defined implementation where the output of one stage becomes the immutable input to the next.

Stage 1: Ingest

The Ingest stage collects raw input—whether JSON, markdown, or other supported assets—and places it into a staging area. According to [archify/docs/article-archify.md](https://github.com/tt-a1i/archify/blob/main/docs/article-archify.md), this step normalizes file paths, computes content digests, and stores data in a temporary, isolated directory. This isolation ensures that the original source remains untouched while the pipeline works with a canonical, digest-verified copy.

Stage 2: Validate

Once staged, content enters the Validate stage where Archify’s schema validators enforce structural and semantic correctness. The system runs validation against workflow, sequence, data-flow, and lifecycle schemas defined in [archify/schemas/README.md](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md). Any violations produce machine-readable diagnostics, and the pipeline aborts immediately on validation failure. This strict gating prevents invalid artifacts from propagating downstream.

Stage 3: Compose

After successful validation, the Compose stage assembles artifacts into their final representation for the target renderer. As implemented in [archify/renderers/dataflow/README.md](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/README.md), this step arranges nodes, edges, stages, and layout constraints according to deterministic rules—such as fixed stage-row grids. The composition process is fully deterministic, meaning identical inputs always generate identical layout structures regardless of execution environment.

Stage 4: Deliver

The Deliver stage handles atomic publication through a candidate-file pattern. Following the specification in [archify/ROADMAP.md](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md), the composed output is written to a candidate file, a SHA-256 receipt is generated, and an atomic rename promotes the candidate to the official artifact. The receipt captures the full diagnostic history, content digest, and the exact stage at which processing completed. This single-rename commit point ensures that readers always see a complete, valid artifact or the previous stable version—never a partial write.

Stage 5: Preview

Finally, the Preview stage launches a lightweight local server that serves the delivered artifact alongside its receipt. As documented in [archify/ROADMAP.md](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md), the preview UI binds to a random loop-back port and updates the visible output only when a new successful receipt is produced. If validation or delivery fails, the preview retains the last-good artifact, providing developers with a stable reference while debugging.

Command-Line Interface for Each Stage

The Archify CLI provides dedicated commands that map one-to-one to the five deterministic stages. The interface enforces strict ordering; attempting to skip a stage results in an explicit error indicating the required preceding stage.

# 1️⃣ Ingest – copy source files into the staging area

archify ingest input.json staging/

# 2️⃣ Validate – run schema checks; exits non-zero on failure

archify validate staging/input.json

# 3️⃣ Compose – generate the renderer-specific HTML/SVG

archify compose --type=dataflow staging/input.json build/output.html

# 4️⃣ Deliver – atomically replace the published artifact

archify deliver build/output.html public/artifact.html

# 5️⃣ Preview – spin up a local preview that only updates on a new receipt

archify preview public/artifact.html

Key Implementation Files

The deterministic behavior of the pipeline is defined across several authoritative source files:

• [archify/schemas/README.md](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) – Defines the validation schemas used in the Validate stage.
• [archify/renderers/dataflow/README.md](https://github.com/tt-a1i/archify/blob/main/archify/renderers/dataflow/README.md) – Describes the deterministic layout rules applied during Compose.
• [archify/ROADMAP.md](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md) – Documents the Deliver and Preview stages, including the atomic rename contract and receipt handling.
• [docs/article-archify.md](https://github.com/tt-a1i/archify/blob/main/docs/article-archify.md) – Provides the high-level overview of the entire pipeline, including the Ingest stage.
• scripts/run-tests.mjs – Executes end-to-end tests that walk through all five stages, ensuring deterministic behavior.

Summary

• The Ingest stage creates isolated, digest-verified copies of raw inputs in a staging area.
• The Validate stage enforces schema compliance through machine-readable diagnostics and fails fast on errors.
• The Compose stage deterministically arranges nodes and edges according to renderer-specific layout rules.
• The Deliver stage uses atomic rename operations and SHA-256 receipts to guarantee publication integrity.
• The Preview stage serves artifacts through a local server that only updates on successful receipt generation, preserving last-good states.

Frequently Asked Questions

What makes the Archify pipeline deterministic?

Each stage has a single, well-defined implementation where the output of one stage becomes the exact, immutable input to the next. The pipeline never mutates previously produced artifacts, ensuring that identical inputs always yield identical outputs and receipts regardless of execution environment or timing.

Can I skip stages when running Archify commands?

No. The CLI enforces strict ordering between the five deterministic stages. Attempting to execute a stage without its prerequisites—such as running archify compose without first validating—results in an explicit error indicating the required preceding stage and its expected inputs.

What happens if validation fails during the pipeline?

The pipeline aborts immediately upon validation failure. The Validate stage produces machine-readable diagnostics detailing schema violations, and no subsequent stages (Compose, Deliver, or Preview) execute. The preview server, if running, retains the last successful artifact since it only updates on receipt of a new valid receipt.

Where is the atomic delivery mechanism implemented?

The atomic delivery mechanism is specified in [archify/ROADMAP.md](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md) and implemented through the Deliver stage. It writes output to a candidate file, generates a SHA-256 receipt containing diagnostics and digests, and uses a single atomic rename as the only commit point to promote the candidate to the official artifact.

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