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

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.

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【/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.

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 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【/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.

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

{
  "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 and 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 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.

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