# How to Migrate Workflow JSON from Schema v1 to v2 Using the Archify CLI

> Easily migrate workflow JSON from v1 to v2 using the Archify CLI. Safely upgrade files, preserve bytes, and get a detailed JSON receipt.

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

---

**Use the `migrate workflow` sub-command to safely upgrade legacy v1 workflow files to the v2 schema while preserving original bytes and generating a detailed JSON receipt.**

Archify persists workflow diagrams as typed JSON adhering to a versioned schema. When upgrading legacy automation definitions authored against the older v1 specification, you can migrate workflow JSON from schema v1 to v2 using the CLI toolchain distributed in `archify/bin/archify.mjs`. The process automatically handles coordinate remapping, viewBox expansion, and diagnostic preservation without mutating source files.

## How the Migration Engine Transforms Documents

The core migration logic resides in `archify/migrations/workflow-v2.mjs`. This module reads the source v1 document, validates its structure, and extracts any pre-existing diagnostics before applying geometric transformations. If the original workflow declares an explicit size in `meta.viewBox` that is too small for modern layout engines, the system automatically expands the capacity to meet v2 requirements.

The engine remaps absolute **x** coordinates onto the new horizontal rank system using the **horizontal rank mapper** exported from `archify/renderers/workflow/workflow-migration-geometry.mjs`. During the final stage, the migrator attaches fresh diagnostics and injects a `migration_probe` node that records the capacity change, then emits a v2-compliant document alongside a structured receipt.

## CLI Syntax and Command Usage

The entry point at `archify/bin/archify.mjs` exposes the migration through the `migrate workflow` sub-command. You must provide distinct source and destination paths.

Basic invocation:

```bash
node archify/bin/archify.mjs migrate workflow \
    path/to/old-workflow.json \
    path/to/new-workflow.json

```

The CLI automatically detects v1 schema source files and emits v2-compatible output at the destination.

### Optional Flags

- `--capacity` – Forces a specific `viewBox` capacity rather than auto-calculating the minimum required size.
- `--quality <profile>` – Specifies a rendering profile (`standard`, `showcase`, etc.). When the source document includes an authored profile, the migration preserves it automatically, as verified in `archify/test/workflow-migration.test.mjs` at lines 270-283.
- `--json` – Outputs a machine-readable receipt instead of human-readable logs.

Example with quality override:

```bash
node archify/bin/archify.mjs migrate workflow old.json new.json --quality showcase

```

## Interpreting the Migration Receipt

Adding the `--json` flag returns a structured receipt matching the return value of the internal `migrateWorkflowDocument` function. This object contains diagnostic metadata and the migrated document:

- `ok` – Boolean indicating overall success.
- `migrationDiagnostics` – Array of issues discovered during the conversion process.
- `newSchemaDiagnostics` – Validation results against the strict v2 schema.
- `oldRequiredViewBox` – Original dimensions (e.g., `[720, 280]`), reported separately from authored capacity per the test at lines 430-440.
- `newRequiredViewBox` – Computed dimensions for v2 compliance (e.g., `[1600, 900]`).
- `document` – The complete migrated workflow object ready for persistence.

Example output:

```json
{
  "ok": true,
  "migrationDiagnostics": [],
  "newSchemaDiagnostics": [],
  "oldRequiredViewBox": [720, 280],
  "newRequiredViewBox": [1600, 900],
  "document": { }
}

```

## Safety Guarantees and Atomicity

The migration toolchain provides strict safety guarantees enforced by the test suite in `archify/test/workflow-migration.test.mjs`. The source file is never modified in-place; the test "migration must not mutate its source bytes" (lines 362-368) asserts that original byte sequences remain untouched throughout the process.

If the migration fails—for instance, when the destination path creates a symlink cycle or matches the source path—the CLI aborts without creating partial files. The test "failed workflow migration never writes its destination" (lines 594-608) verifies this atomic behavior, ensuring your filesystem remains clean even when operations encounter errors.

## Summary

- The `migrate workflow` sub-command in `archify/bin/archify.mjs` automates the upgrade from v1 to v2 schema.
- Core logic lives in `archify/migrations/workflow-v2.mjs` with geometric calculations in `archify/renderers/workflow/workflow-migration-geometry.mjs`.
- The process expands `meta.viewBox` capacity and remaps coordinates using the horizontal rank mapper.
- Use `--json` to receive a detailed receipt containing `oldRequiredViewBox`, `newRequiredViewBox`, and diagnostic arrays.
- Original files are read-only; failed migrations never write partial destinations.

## Frequently Asked Questions

### Does the migration modify the original v1 workflow file?

No. According to the test "migration must not mutate its source bytes" in `archify/test/workflow-migration.test.mjs` at lines 362-368, the CLI treats the source as immutable. It reads the original bytes and writes a completely new file at the destination path, leaving the legacy document intact for rollback purposes.

### What information does the migration receipt contain?

The receipt contains an `ok` boolean, `migrationDiagnostics` for conversion issues, `newSchemaDiagnostics` for v2 validation results, and dimensional tracking via `oldRequiredViewBox` and `newRequiredViewBox`. When using the `--json` flag, this receipt prints to stdout for piping into other tools like `jq`.

### How does the CLI handle coordinate differences between v1 and v2?

The migration uses the **horizontal rank mapper** from `archify/renderers/workflow/workflow-migration-geometry.mjs` to translate absolute **x** coordinates from the v1 absolute positioning system into the v2 horizontal rank system. This ensures visual fidelity while adopting the new layout engine's constraints.

### What happens if the destination path is invalid?

The CLI performs pre-flight checks before writing. If the destination is a symlink cycle or identical to the source path, the operation aborts without creating a file. As tested in `archify/test/workflow-migration.test.mjs` lines 594-608, failed migrations never write their destination, preventing corruption or data loss.