≡quivalence ≡ngine Overview

Equivalence Engine logo

The ≡quivalence ≡ngine is the core binary of the Equivalence Adaptation Ecosystem. Written in high-performance D, it provides a fast, version-aware adaptation processor that migrates source code and configuration files between library/framework versions using lightweight, human-readable SDL rulesets.

Technical overview

A directed acyclic graph (DAG)-based engine for computing equivalence between software implementations, tool calls, or any other custom mappings. Nodes represent versions, contexts, or intents; SDL rulesets define directed edges; the engine resolves the shortest path from source to target and applies the composed transformations.

Purpose

As libraries and frameworks evolve, breaking changes make migrations painful and slow. The ≡quivalence ≡ngine is built to solve this. Instead of simple search-and-replace, the engine: * Understands Versions: Uses SemVer parsing to resolve the exact migration chain from version A to version B. * Discovers Shortest Path: If no direct rule exists from 1.0 to 3.0, but rules exist for 1.0→2.0 and 2.0→3.0, it automatically chained-applies the rulesets via the shortest path. * Integrates with Git: Dynamically retrieves rulesets from local folders or remote Git repositories on-the-fly.

Ecosystem Components

The ecosystem is split into 5 modular, cooperative repositories:

  • ≡quivalence ≡ngine (this component): The CLI binary processor.

  • Equivalence Engine Action: A modular GitHub Action to automate adaptation in CI pipelines.

  • libequivalence: The core D library wrapping rules parsing and path mappings, used by the CLI.

  • Equivalence Rules: Code: The official rules library for code files (e.g. PyQt5 to PyQt6). Planned rename: equivalence-rules-code.

  • Equivalence Rules: Filesystem: Mappings translating abstract folder references across Operating Systems. Planned rename: equivalence-rules-filesystem.

Next Steps