# How Archify Handles Errors and Diagnostics During Validation and Delivery

> Learn how Archify ensures actionable error handling with machine-readable JSON receipts during validation and delivery. Discover deterministic, repairable fixes without stack traces.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Archify treats validation and delivery as deterministic stages that always emit a machine-readable JSON receipt containing precise diagnostics and repairable fixes, ensuring no stack traces reach stdout and every failure is actionable.**

When building automated workflows with tt-a1i/archify, understanding the error handling architecture is critical for CI/CD integration. Archify implements a *fail-closed* strategy where both validation and delivery operations produce structured JSON receipts that serve as the single source of truth for pipeline status. This deterministic approach eliminates ambiguous exit states and provides automated agents with the exact context needed to self-heal issues.

## The Validation Stage and Structured Error Reporting

When you invoke `archify.mjs validate … --json`, the CLI executes a rigorous multi-phase inspection that guarantees machine-parseable output regardless of success or failure.

### JSON Schema Validation and Geometry Checks

According to the source code in `bin/archify.mjs`, the validation process first parses the input JSON against the appropriate schema (such as [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)). It then executes a series of deterministic geometry and composition checks including duplicate ID detection, edge-crossing validation, label clearance analysis, and container-border run verification. If any check fails, the command immediately exits with a non-zero status while suppressing all Node stack traces from stdout.

### The Receipt Contract

As documented in [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) (lines 73-81), every validation operation returns a single JSON object containing three critical fields:

- **`ok`**: A boolean indicating overall success
- **`stage`**: A string identifying the failing phase (e.g., `"validate"`)
- **`diagnostics`**: An array of structured error objects, each containing:
  - `subject`: The affected element identifier (e.g., `"relationship[12]"`)
  - `message`: A human-readable description of the issue
  - `supportedFixes`: An array of actionable repair strategies

The delivery contract in [`references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/references/delivery-contract.md) (lines 57-80) mandates that this receipt format remain consistent across both validation and delivery commands, ensuring downstream tooling can rely on a stable API contract.

```bash

# Run validation and capture structured diagnostics

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

```

```json
{
  "ok": false,
  "stage": "validate",
  "diagnostics": [
    {
      "subject": "relationship[12]",
      "message": "duplicate ID 'order'",
      "supportedFixes": ["renameId", "remove"]
    }
  ]
}

```

## The Delivery Stage and Diagnostic Aggregation

After successful validation, the `deliver` command extends the error handling pattern to encompass rendering and asset management while maintaining the same JSON receipt contract.

### Rendering Pipeline and Final Checks

When executing `archify.mjs deliver … --json`, the CLI runs the renderer followed by a final HTML checker. During this process, it captures delivery-specific issues such as missing PNG assets, broken hyperlinks, or template rendering failures. The implementation in `bin/archify.mjs` (lines 267-333) constructs a comprehensive receipt that preserves the full audit trail.

### Merged Receipt Structure

The delivery receipt contains both the original validation results and any new delivery-specific diagnostics. This merged structure ensures that the entire pipeline remains auditable through a single JSON payload, as required by the delivery contract. If validation had previously failed, those diagnostics are included alongside any new rendering issues, providing complete context for failure analysis.

```bash

# Execute delivery; failures still return valid JSON receipts

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

```

```json
{
  "ok": false,
  "stage": "deliver",
  "validation": { "ok": true },
  "diagnostics": [
    {
      "subject": "artifact[3]",
      "message": "missing PNG asset",
      "supportedFixes": ["addAsset"]
    }
  ]
}

```

## Error Handling Policy and Repair Workflows

Archify enforces three strict policies that govern how errors propagate through the system.

### Deterministic JSON Reporting

**Deterministic reporting** guarantees that every failure is represented by a structured JSON object and that a non-zero exit code is never reported as success. Per [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md), stack traces and debugging information are either forwarded to `stderr` or omitted entirely, ensuring that `stdout` contains only parseable data. This design allows automated agents to trust the JSON receipt as the sole source of truth for pipeline state.

### The Repair Loop with supportedFixes

Each diagnostic entry includes a `supportedFixes` array that enables automated repair workflows. The [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) (lines 65-68) documents this pattern, advising agents to "repair the named subject and use the listed `supportedFixes` before trying another change." This creates a tight feedback loop where validation failures can trigger automatic remediation scripts that apply the suggested fixes and re-run the validation step until the receipt returns `"ok": true`.

### Zero-Install Reproducibility

Archify guarantees that validation, rendering, and diagnostics execute without external dependencies beyond Node.js ≥ 18. This **zero-install guarantee** ensures that the same receipt can be reproduced on any compliant environment, making the tool suitable for air-gapped CI systems and automated agent workflows where reproducible evidence is essential.

## Summary

- **Machine-readable receipts**: Both `validate --json` and `deliver --json` emit structured JSON objects containing `ok`, `stage`, and `diagnostics` fields, as implemented in `bin/archify.mjs`.
- **Fail-closed architecture**: Non-zero exit codes always correlate with `"ok": false`, and stdout never contains unstructured stack traces.
- **Repairable diagnostics**: Every error includes `supportedFixes` enabling automated remediation loops documented in [`authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/authoring-cookbook.md).
- **Audit trail preservation**: Delivery receipts merge validation and rendering diagnostics into a single payload for complete pipeline traceability.
- **Reproducible execution**: Error handling requires zero external dependencies, functioning identically across Node ≥ 18 environments.

## Frequently Asked Questions

### What format does Archify use for error reporting?

Archify emits a structured JSON receipt containing an `ok` boolean, a `stage` string identifying the operation phase, and a `diagnostics` array. Each diagnostic object specifies the affected `subject`, a human-readable `message`, and an array of `supportedFixes` for automated repair.

### How does Archify prevent noisy stack traces from breaking automation?

The CLI implementation in `bin/archify.mjs` explicitly suppresses Node stack traces from stdout, routing them to `stderr` only when debugging is enabled. This ensures that automated parsers can always expect valid JSON on standard output, even when the process exits with a non-zero status code.

### Can delivery operations report errors from earlier validation stages?

Yes. The delivery receipt format defined in [`references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/references/delivery-contract.md) includes both a `validation` object containing earlier results and a top-level `diagnostics` array for delivery-specific issues. This merged structure provides complete visibility into failures occurring at any pipeline stage.

### How do automated agents repair Archify validation failures?

Agents inspect the `supportedFixes` array within each diagnostic entry to determine available remediation strategies. According to [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) and [`authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/authoring-cookbook.md), agents should apply the listed fixes to the named subject and re-run the validation command, creating an iterative repair loop until all diagnostics are resolved.