Skip to content

Eleguá

Domain-agnostic, multi-tier test harness for validating mathematical equivalence.

What it does — Prove that two implementations of the same mathematical system produce equivalent results. Define test cases in TOML, write an Adapter for each implementation, and let Eleguá tell you whether they agree — and at what level of analysis.
Use this when — You need to validate a port, rewrite, or alternative implementation of a symbolic math library.
Outcome — Understand the architecture, choose your entry path, and find the right guide for your role.

Eleguá proves that two implementations of the same mathematical system produce equivalent results. It runs identical symbolic actions on a high-fidelity Oracle and one or more Implementations Under Test (IUT), then compares outputs through a 4-layer pipeline — from fast structural equality to deeper semantic and invariant-based checks — stopping at the first layer that confirms a match.

In short, define test cases in TOML, write an Adapter for each implementation, and let Eleguá tell you whether they agree — and at what level of analysis.

Key features

  • Multi-tier execution — validate results across Oracle and IUT implementations
  • 4-layer comparison pipeline — progressive refinement from identity to semantic and invariant-based comparison
  • TOML-based test definitions — declarative, language-agnostic test specs
  • Property-based testing utilities — Hypothesis-based law checks alongside the comparison pipeline
  • SHA-256 blob store — transparent handling of large symbolic expressions
  • State machine enforcement — validated task lifecycle transitions

Execution model at a glance

TOML fixture → EleguaTask → Adapter.execute() → ValidationToken → Comparison Pipeline → pass/fail

Choose your path

Based on your goal, consider the following entry points:

1. Evaluate Eleguá

If you want to run a quick test using the built-in stubs: - Getting started — install and run your first comparison - Architecture — understand the three-tier model

2. Build an adapter

If you want to connect Eleguá to your own symbolic engine: - Task lifecycle - Writing an adapter - Comparison pipeline

3. Contribute

If you want to help develop the Eleguá core harness: - Development — set up the local contributor environment - API reference — auto-generated from source

The remaining guide pages (TOML format, Property testing, Blob store, Oracle servers) can be read in any order as needed.