# Archify Workflow Schema v1 to v2 Migration Runtime: Implementation and Location

> Find the Archify workflow schema v1 to v2 migration runtime in archify/migrations/workflow-v2.mjs. Discover how migrateWorkflowDocument automatically handles schema updates during compilation.

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

---

**Archify performs workflow schema v1 to v2 migration at runtime in the `archify/migrations/workflow-v2.mjs` module, specifically through the `migrateWorkflowDocument()` function, which is automatically invoked by the workflow compiler when it detects a legacy `schema_version: 1` document.**

The **Archify** open-source architecture includes a transparent runtime migration system that upgrades legacy workflow documents from **schema v1** to **schema v2** without manual intervention. When the platform encounters deprecated workflow definitions, it executes a structured transformation pipeline that validates, probes, and remaps the document geometry before compilation. This article examines the exact runtime location, implementation details, and programmatic interfaces for the **workflow schema v1 to v2 migration** in the `tt-a1i/archify` repository.

## Core Migration Module Location

The primary **runtime migration logic** resides in **`archify/migrations/workflow-v2.mjs`**. This module exports the public entry point **`migrateWorkflowDocument(inputWorkflow)`**, which orchestrates the entire transformation process from legacy v1 structures to the current v2 schema.

### Five-Stage Migration Pipeline

When invoked, `migrateWorkflowDocument()` executes a systematic transformation pipeline:

1. **Validation**: Validates the incoming JSON workflow expects a v1 document structure and conforms to legacy constraints.
2. **Discovery**: Runs compilation probes including **`legacyLayoutProbe`** and **`legacyRequirementProbe`** to discover the original layout dimensions and capacity requirements embedded in the v1 document.
3. **Planning**: Generates a rank-mapping plan using geometry helpers such as **`createMappedWorkflowCandidate`** to calculate the necessary spatial transformations.
4. **Application**: Applies the mapping, conditionally expands the **viewBox** if the migrated content exceeds original boundaries, and re-validates the resulting document against v2 schema constraints.
5. **Result Construction**: Returns a detailed result object containing `diagnostics`, the migrated `document`, and metadata regarding required **view-box expansions**.

The module also exports **`serializeMigratedWorkflow`**, which handles the final serialization of the transformed document.

## Automatic Runtime Integration with the Workflow Compiler

The migration is transparently triggered by the **workflow compiler** located in **`archify/renderers/workflow/workflow-compiler.mjs`**. This integration ensures that v1 workflows are automatically upgraded before they enter the rendering pipeline.

### Schema Version Detection

When the compiler processes a workflow, it inspects the `schema_version` property. If the value equals **1**, the compiler automatically calls `migrateWorkflowDocument()` before proceeding with the normal compilation pipeline. This detection mechanism ensures **backward compatibility** without requiring manual upgrades of legacy workflow files.

The compiler passes the raw JSON workflow object to the migration function and expects a result object with an `ok` property. If `result.ok` is true, the compiler proceeds with the migrated v2 document; otherwise, it surfaces the `migrationDiagnostics` through the standard compilation error pathway.

### Compiler-Mediated Migration Example

```js
// Example: the compiler automatically migrates during compilation
import { compileWorkflow } from
  'archify/renderers/workflow/workflow-compiler.mjs';
import fs from 'fs';

// The compiler accepts a raw JSON workflow (v1 or v2)
const rawWorkflow = JSON.parse(
  fs.readFileSync('my-workflow-v1.workflow.json', 'utf‑8')
);

// Compile – migration happens under the hood if needed
const compileResult = compileWorkflow({ workflow: rawWorkflow });

if (compileResult.ok) {
  console.log('Compiled workflow (v2) ready for rendering');
} else {
  console.error('Compilation (and migration) failed:', compileResult.diagnostics);
}

```

## Manual Migration and Programmatic Usage

Developers can invoke the **workflow schema v1 to v2 migration** programmatically without using the compiler, enabling custom migration workflows or bulk upgrade scripts.

```js
// Example: programmatically migrate a v1 workflow JSON object
import { migrateWorkflowDocument } from
  'archify/migrations/workflow-v2.mjs';
import fs from 'fs';

// Load a v1 workflow from disk
const v1Workflow = JSON.parse(
  fs.readFileSync('my-workflow-v1.workflow.json', 'utf‑8')
);

// Perform the migration
const result = migrateWorkflowDocument(v1Workflow);

if (result.ok) {
  // Migration succeeded – write the v2 workflow back to disk
  fs.writeFileSync(
    'my-workflow-v2.workflow.json',
    JSON.stringify(result.document, null, 2) + '\n'
  );
  console.log('Migration completed successfully');
} else {
  // Handle migration errors; diagnostics describe the problem
  console.error('Migration failed:', result.migrationDiagnostics);
}

```

When calling `migrateWorkflowDocument()` directly, the function returns an object containing the upgraded document and diagnostic information about any viewBox adjustments or transformation issues encountered during the geometry remapping phase.

## Testing and Verification Infrastructure

### CLI Smoke Testing

The **`scripts/package-smoke.mjs`** script exercises the migration runtime through a migration **"receipt"** check. This command-line utility runs the actual migration path and verifies that the migrated file is produced correctly, ensuring the runtime logic functions as expected in packaged distributions.

### Unit Test Coverage

Comprehensive test coverage exists in **`archify/test/workflow-migration.test.mjs`**, which validates the migration logic against edge cases. This suite ensures that geometry calculations, probe executions, and schema transformations behave correctly across various v1 workflow configurations.

## Summary

- **Primary Location**: The **Archify workflow schema v1 to v2 migration runtime** is implemented in **`archify/migrations/workflow-v2.mjs`**, specifically within the **`migrateWorkflowDocument()`** function.
- **Automatic Trigger**: The **workflow compiler** (`workflow-compiler.mjs`) automatically detects `schema_version: 1` and invokes the migration before proceeding with compilation.
- **Discovery Mechanism**: Migration uses **probes** (`legacyLayoutProbe`, `legacyRequirementProbe`) to analyze v1 layout requirements before generating the v2 geometry mapping.
- **Programmatic Access**: Developers can import `migrateWorkflowDocument` directly for manual migrations or bulk upgrades outside the compiler context.
- **Validation**: The runtime is verified through both **CLI smoke tests** (`package-smoke.mjs`) and comprehensive **unit tests** (`workflow-migration.test.mjs`).

## Frequently Asked Questions

### Where exactly is the Archify workflow schema v1 to v2 migration runtime located?

The migration runtime is located in the **`archify/migrations/workflow-v2.mjs`** module within the `tt-a1i/archify` repository. The public API entry point is the **`migrateWorkflowDocument(inputWorkflow)`** function, which handles the complete transformation pipeline from validation through final document generation.

### How does the Archify compiler know when to trigger the v1 to v2 migration?

The **workflow compiler** (`archify/renderers/workflow/workflow-compiler.mjs`) inspects the `schema_version` field of incoming workflow documents. When it detects a value of **1**, it automatically calls `migrateWorkflowDocument()` before proceeding with the standard v2 compilation pipeline, ensuring seamless backward compatibility.

### What probes are used during the v1 to v2 workflow migration?

The migration utilizes **`legacyLayoutProbe`** and **`legacyRequirementProbe`** to analyze the original v1 document structure. These probes discover the legacy layout dimensions and capacity requirements, which feed into the geometry mapping functions like **`createMappedWorkflowCandidate`** to calculate the correct v2 spatial representation.

### Can I run the Archify workflow migration manually without using the compiler?

Yes, you can programmatically invoke **`migrateWorkflowDocument()`** by importing it from `archify/migrations/workflow-v2.mjs`. This allows for manual migrations, batch processing of legacy files, or integration into custom build pipelines independent of the standard compiler workflow.