Archify Migration Tool: Workflow Schema v1 to v2 Upgrade Guide

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.

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

# 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.

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