# How to Diagnose Workflow v2 Geometry Issues in Archify: A Complete Troubleshooting Guide

> Diagnose Archify v2 geometry issues caused by invalid metadata, SVG coordinates, or schema mismatches. Resolve them with CLI validation, SVG inspection, or migration tools.

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

---

**Geometry issues in Archify v2 workflows almost always stem from invalid layout metadata, malformed SVG coordinates, or schema version mismatches—each fixable through CLI validation, SVG inspection, or migration tools.**

Archify renders workflow diagrams from a JSON contract that describes nodes, edges, and layout metadata. **Workflow v2 geometry issues** typically surface when the readable-v2 contract contains malformed data or when the renderer produces invalid SVG elements. This guide walks through the diagnostic process using the actual source code from `tt-a1i/archify`.

## Validate the JSON Contract First

Start with the CLI validator to catch contract-level problems before investigating visual output. The validation logic in `scripts/package-smoke.mjs` enforces strict schema compliance.

```bash
node scripts/package-smoke.mjs validate workflow path/to/your.workflow.json --json

```

If validation fails, the error originates at lines 242–246 of `package-smoke.mjs`, where the script throws on malformed contract or incorrect column counts【/scripts/package-smoke.mjs#L242-L246】. Common validation failures include:

- Missing `columns`, `nodes`, or `edges` fields
- Incorrect data types in layout metadata
- Malformed `diagnostics` array structure

Compare your file against [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json)【/examples/agent-tool-call.workflow.json】—the canonical reference for a valid readable-v2 contract.

## Inspect Rendered SVG for Malformed Geometry

When validation passes but visuals break, examine the generated SVG for coordinate corruption. The renderer includes a guard that filters out `NaN` or `Infinity` values, which can leave visual layouts incomplete.

```bash
node scripts/package-smoke.mjs deliver workflow path/to/your.workflow.json \
    output/workflow.html --json

```

Open the resulting HTML and inspect `<path>` and `<polyline>` elements. Search for malformed attributes in the `d` or `points` properties. The geometry-validation snippet at lines 5538–5550 of [`generated/maka-regenerated.workflow.visual-check.html`](https://github.com/tt-a1i/archify/blob/main/generated/maka-regenerated.workflow.visual-check.html) shows the exact filtering logic that discards invalid coordinates【/generated/maka-regenerated.workflow.visual-check.html#L5538-L5550】.

Use [`examples/workflow-agent-tool-call-rendered.html`](https://github.com/tt-a1i/archify/blob/main/examples/workflow-agent-tool-call-rendered.html)【/examples/workflow-agent-tool-call-rendered.html】 as a visual baseline for comparison.

## Check for Schema Version Mismatches

Workflows authored for older schemas (readable-v1) may render incorrectly under v2 processing. The migration tool converts legacy contracts and validates the output schema.

```bash
node scripts/package-smoke.mjs migrate workflow legacy.workflow.json migrated.workflow.json

```

The migration logic at lines 269–273 asserts that the output schema equals `schema-v2` and aborts if this check fails【/scripts/package-smoke.mjs#L269-L273】. If migration fails, regenerate the workflow JSON using the latest schema or manually update the structure to v2 format.

## Complete Diagnostic Workflow

Follow this sequence to systematically isolate **workflow v2 geometry issues**:

1. **Run contract validation** — catch JSON structure problems early
2. **Render and inspect SVG** — identify coordinate-level corruption
3. **Migrate if version mismatch suspected** — ensure readable-v2 compatibility
4. **Diff against reference files** — compare `nodes` and `edges` arrays with working examples
5. **Execute automated tests** — run `npm test` or `scripts/run-tests.mjs` to validate against `archify/test/workflow-semantic-contract.test.mjs`

## Minimal Valid Workflow v2 Contract

```js
{
  "contract": "readable-v2",
  "type": "workflow",
  "nodes": [{ "id": "start", "label": "Start", "lane": 0 }],
  "edges": [{ "source": "start", "target": "end", "label": "" }],
  "columns": 6,
  "diagnostics": []
}

```

This structure from the test suite demonstrates the required fields for proper geometry calculation.

## Summary

- **Invalid layout metadata** — fix by running `package-smoke.mjs validate` and correcting JSON structure
- **Malformed SVG geometry** — detect by inspecting rendered HTML for `nan`/`infinity` in path coordinates
- **Version mismatch** — resolve using the `migrate` command to convert to readable-v2 schema
- Reference files at [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json) and [`examples/workflow-agent-tool-call-rendered.html`](https://github.com/tt-a1i/archify/blob/main/examples/workflow-agent-tool-call-rendered.html) provide working baselines
- Automated validation through `archify/test/workflow-semantic-contract.test.mjs` ensures long-term contract compliance

## Frequently Asked Questions

### What causes NaN or Infinity values in Archify SVG output?

The renderer generates these when node or edge coordinates calculate to undefined values, typically due to missing layout fields or malformed numeric inputs in the workflow JSON. The geometry guard in [`maka-regenerated.workflow.visual-check.html`](https://github.com/tt-a1i/archify/blob/main/maka-regenerated.workflow.visual-check.html) filters these values, which produces incomplete visual layouts rather than crashing.

### How do I know if my workflow uses the wrong schema version?

Run `node scripts/package-smoke.mjs validate` — validation errors referencing unknown fields or unexpected structures often indicate v1 authorship. The readable-v2 contract requires explicit `contract: "readable-v2"` and specific `columns`, `nodes`, `edges` field arrangements visible in the reference examples.

### Can I fix geometry issues without regenerating the entire workflow?

Yes. Many issues resolve through targeted JSON edits: add missing `columns` values, ensure all nodes have valid `lane` assignments, and verify edge `source`/`target` references point to existing node IDs. Re-validate after each change using the CLI validator.

### Where does Archify store geometry validation tests?

The primary test suite lives at `archify/test/workflow-semantic-contract.test.mjs` according to the source analysis. Run this through `npm test` or `scripts/run-tests.mjs` to verify contract compliance against readable-v2 geometry rules.