# Archify Migration Tool: Workflow Schema v1 to v2 Upgrade Guide

> Upgrade your Archify migration tool workflow schema from v1 to v2. This guide details remapping coordinates, separating viewBox, and validating your v2 schema for seamless migration.

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

---

**The Archify migration tool converts legacy v1 workflow JSON documents into fully-validated v2 schema by remapping absolute X coordinates onto deterministic rank centers while strictly separating viewBox capacity from layout geometry.**

The Archify repository stores workflow diagrams as typed JSON IR documents that must pass validation against versioned schemas. Upgrading from workflow schema v1 to v2 requires transforming documents that relied on absolute **x** coordinates and dual-purpose `viewBox` metadata into a format that enforces deterministic, reproducible layouts. The migration pipeline accomplishes this through a sequence of compilation, geometric projection, and validation steps implemented in the source code.

## Schema v1 vs. v2: Key Differences

Understanding the structural changes between versions clarifies why migration is necessary.

**Schema v1** relied on absolute **x** coordinates for node positioning and treated the optional `viewBox` property as both a layout guide and implicit canvas capacity. This design produced "shaky" layouts that varied across machines and conflated the author’s intended zoom level with the actual space required by the diagram.

**Schema v2** introduces a clean architectural separation. The `viewBox` in `meta.viewBox` now reflects only the *required* canvas size (capacity), while all layout coordinates are projected onto deterministic rank centers. This ensures that compiling the same workflow on different environments yields identical geometric results.

## The 8-Step Migration Pipeline

The `migrateWorkflowDocument` function in `archify/migrations/workflow-v2.mjs` orchestrates the conversion through eight distinct phases.

### 1. Input Validation

The process begins by verifying that the supplied object is a proper JSON workflow. Any schema violations are collected into `schemaDiagnostics` and reported immediately. In `workflow-v2.mjs` (lines 28-36), this check prevents malformed documents from entering the compilation stage.

### 2. Legacy Compilation

The tool compiles the v1 document using `compileWorkflow` to obtain the *legacy* rank plan. This step also generates a *probe* that reveals the true layout requirement without treating the authored `meta.viewBox` as intrinsic capacity, as implemented in `workflow-v2.mjs` (lines 73-84).

### 3. Capacity Measurement

The `legacyRequirementProbe` utility removes the `viewBox` from the source object, allowing the compiler to measure the *true* layout requirement based on node and edge geometry alone. This measurement occurs in `workflow-v2.mjs` (lines 65-72).

### 4. Rank-Center Projection

Two helper projections prepare the geometry for remapping:

- **`intrinsicWorkflow`** strips the authored `viewBox` so the compiler can compute the intrinsic rank plan (`workflow-migration-geometry.mjs`, lines 12-18).
- **`planningWorkflow`** further removes any author-provided geometry that might become invalid after X-coordinate remapping (`workflow-migration-geometry.mjs`, lines 25-42).

### 5. Horizontal Rank Mapping

The `createHorizontalRankMapper` function builds a deterministic piece-wise-linear function. This mapper translates every legacy **x** coordinate from the absolute positioning system onto the new rank-center positions defined by the v2 schema. The implementation resides in `workflow-migration-geometry.mjs` (lines 65-99).

### 6. Coordinate Remapping

`mapExplicitCoordinates` traverses every edge in the workflow and rewrites absolute **x** pins using the rank mapper. This function emits an audit trail of changed coordinates for downstream reporting (`workflow-migration-geometry.mjs`, lines 7-33).

### 7. View-Box Expansion

After remapping, the compiler may report a *viewBox-capacity* diagnostic. If the migrated `meta.viewBox` is smaller than the newly required size, the tool expands the viewBox monotonically to fit the content. This safety check appears in `workflow-v2.mjs` (lines 29-41).

### 8. Final Validation

The migrated document undergoes a final compilation and validation pass against the strict v2 schema. If any new diagnostics emerge—indicating a logic error in the migration—the process fails, ensuring the output is a *stand-alone* v2 workflow (`workflow-v2.mjs`, lines 44-66).

Upon success, `migrateWorkflowDocument` returns an object containing:
- `ok: true`
- `document` — the migrated v2 JSON
- `changedCoordinates` — a list of every X-pin that was moved
- `oldRequiredViewBox` and `newRequiredViewBox` — the capacity before and after expansion

## Programmatic API Usage

Import the migration utilities to upgrade workflows within your own scripts.

```javascript
// Import the migration API
import { migrateWorkflowDocument, serializeMigratedWorkflow } from
  './archify/migrations/workflow-v2.mjs';
import fs from 'fs';

// Load a legacy workflow (v1 JSON)
const legacyJson = JSON.parse(
  fs.readFileSync('examples/legacy-workflow.workflow.json', 'utf8')
);

// Run the migration
const result = migrateWorkflowDocument(legacyJson);

if (!result.ok) {
  console.error('Migration failed:', result.migrationDiagnostics);
  process.exit(1);
}

// Inspect what changed
console.log('Changed X-coordinates:', result.changedCoordinates);
console.log('Old viewBox:', result.oldRequiredViewBox);
console.log('New viewBox:', result.newRequiredViewBox);

// Persist the migrated v2 document
fs.writeFileSync(
  'examples/migrated-workflow.workflow.json',
  serializeMigratedWorkflow(result.document),
);

```

The `serializeMigratedWorkflow` helper pretty-prints the result for persistence and is defined in `workflow-v2.mjs` (lines 77-80).

## Command-Line Interface

The CLI provides an atomic migration command that only writes the destination file after a successful round-trip compilation.

```bash

# Migrate a v1 workflow to v2, writing the result to <dest>.workflow.json

node archify/bin/archify.mjs migrate workflow \
  examples/legacy-workflow.workflow.json \
  examples/migrated-workflow.workflow.json

```

The CLI entry point in `archify/bin/archify.mjs` handles the `migrate` sub-command and exits with a non-zero status if any diagnostic prevents migration, guaranteeing that source files are never left in a half-written state.

## Why Upgrade to Schema v2?

Migrating to schema v2 provides three critical improvements enforced by the tool’s logic:

**Deterministic Layout** — V2 uses rank-center coordinates that are reproducible across machines, eliminating the layout instability that plagued v1 documents.

**Separate Capacity Concerns** — The `meta.viewBox` now strictly reflects the required canvas size, while the migration process expands it only when strictly necessary based on the `newRequiredViewBox` measurement.

**Atomic Operations** — Whether using the CLI or the programmatic API, the destination file is written only after the migrated document passes final validation, ensuring atomic upgrades.

## Summary

- The **Archify migration tool** converts workflow schema v1 documents to v2 through an 8-step pipeline involving validation, compilation, and geometric projection.
- **Absolute X coordinates** from v1 are remapped to **deterministic rank centers** in v2 using `createHorizontalRankMapper` and `mapExplicitCoordinates` in `workflow-migration-geometry.mjs`.
- The `viewBox` capacity is measured independently from layout using `legacyRequirementProbe`, then expanded monotonically if the migrated content exceeds the original bounds.
- The main orchestration logic resides in `archify/migrations/workflow-v2.mjs`, which exposes `migrateWorkflowDocument` and `serializeMigratedWorkflow`.
- Both the **programmatic API** and **CLI** guarantee atomic writes, ensuring destination files are only created after successful validation against the v2 schema.

## Frequently Asked Questions

### What is the primary difference between workflow schema v1 and v2?

Schema v1 stored absolute **x** coordinates and used `viewBox` ambiguously as both a viewport and capacity indicator. Schema v2 separates these concerns: layout uses deterministic rank-center coordinates, while `viewBox` strictly defines the required canvas capacity. This separation eliminates layout drift across different environments.

### How does the migration tool handle existing X coordinates?

The tool builds a deterministic piece-wise-linear mapper via `createHorizontalRankMapper` that projects every legacy absolute **x** coordinate onto the center of its corresponding rank. The `mapExplicitCoordinates` function then rewrites all edge pins using this mapping, generating an audit trail in `changedCoordinates`.

### What happens if the legacy viewBox is too small for the migrated layout?

During the capacity measurement phase, the tool removes the authored `viewBox` and measures the *intrinsic* layout requirement. If the legacy `viewBox` is smaller than this requirement, the migration expands it monotonically to fit. This expansion is recorded in `oldRequiredViewBox` and `newRequiredViewBox`.

### Is the migration process atomic?

Yes. The CLI in `archify/bin/archify.mjs` and the recommended programmatic usage both validate the v2 document completely before writing to the destination. If any diagnostic fails during the final validation step, the process exits without writing files, ensuring you never end up with a half-migrated document.