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

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

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

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

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