wyrm-math: A Conditionally-Sound Symbolic Algebra Engine

wyrm-math enables sound, manipulative math interfaces

wyrm-math is a conditionally-sound symbolic algebra engine designed for building interactive math interfaces where users solve equations by manipulating terms—such as dragging terms across an equals sign or expanding powers. Unlike traditional solvers that validate a final answer, wyrm-math ensures that every reachable state is sound by construction, meaning illegal moves are impossible by design.

Core Architecture: Soundness by Construction

The engine operates on the principle that equations are never validated; they are only transformed via rewrite rules. This ensures that any state the user reaches is mathematically valid.

Conditional Soundness and Assumptions

Because some algebraic moves are only valid under specific conditions, wyrm-math treats these conditions as first-class Assumptions. These assumptions travel with the equation to maintain mathematical integrity:

• Restrictions: Moves that could potentially lose solutions (e.g., dividing by a variable b requires the assumption b ≠ 0).
• Extensions: Moves that could introduce extraneous solutions (e.g., squaring both sides), which carry an obligation to be settled by a checkSolution process.
• Pinned Assumptions: User-defined "what-if" scenarios (e.g., pinning x = 0).

Exact Arithmetic

To avoid the precision errors associated with floating-point math, wyrm-math uses bigint rationals for all arithmetic. Irrational roots (like √2) are treated as undefined points rather than approximations, adhering to a strict engine-wide soundness contract of "truth-where-both-defined."

Technical Implementation

Built in pure TypeScript with zero dependencies and no DOM requirements, the engine is designed to run in any environment, including Node.js, browsers, web workers, and native webviews.

Expression Trees and AST

The engine uses an immutable Abstract Syntax Tree (AST) with stable node IDs. It employs N-ary Sum and Product nodes, representing subtraction as a sum of a negative and an addition is handled via smart constructors to maintain structural invariants.

Move Enumeration and Layout

One of the engine's primary features is enumerateMoves(judgment), which identifies every legal algebraic affordance available in the current state. This allows UI developers to place gesture anchors (handles and drop targets) exactly where a legal move can be performed.

To facilitate smooth animations, the engine provides layoutNode, which maps trees to positioned, id-keyed boxes and glyphs using static metric tables. Because subtree geometry is context-independent, renderers can match nodes across rewrites and animate them rigidly.

Feature Set and Rule Library

wyrm-math includes approximately 25 built-in rules covering a wide range of algebraic operations:

• Linear Equations: Basic term movement and like-term simplification.
• Distribution and Fractions: Expanding brackets and handling fractional expressions.
• Exponent Laws: Rules for powers and radicals.
• Inequalities: Sign-aware rules that flip the relation when multiplying or dividing by a negative.
• Quadratics: Handling zero-product properties and branching (e.g., x² = 9 branches into x = 3 or x = -3).

Community Perspectives and Use Cases

Community discussion highlights the potential for wyrm-math to shift the educational paradigm of algebra from a "problem to be solved" to a "puzzle to be manipulated."

"I appreciate how this frames algebra as a puzzle instead of a problem :)"

Other developers have suggested expanding the engine's utility into theorem proving and equational reasoning for functional programming, noting that a visual interface for rule-application could bridge the gap between manual equations and formal theorem provers. Additionally, some developers currently using Python-based tools like SymPy via Pyodide have noted the limitations of browser-based Python and the potential value of a native TypeScript implementation like wyrm-math.