[API Coherence] Report for Feb 20, 2026 - Solver & BitVector APIs

[github-actions[bot]]

Summary

This is the first systematic API coherence analysis for Z3's multi-language bindings. This run analyzed 8 API families covering approximately 25 APIs across 7 language bindings.

APIs Analyzed in This Run

• Context creation and configuration
• Solver core APIs (push, pop, check, assert, get_model)
• Solver diagnostic APIs (units, trail, statistics, reason_unknown, assertions)
• Solver congruence closure APIs ⚠️ (new in recent versions)
• Solver file I/O APIs (from_file, from_string)
• BitVector extension APIs (sign_ext, zero_ext)
• BitVector rotation APIs (rotate_left, rotate_right, ext_rotate)
• Array theory basics (select, store, const_array)

Key Findings

• Total issues found: 2 (both medium priority)
• Resolution updates: N/A (first run)
• Overall coherence: Good - most core APIs are well-supported across all languages

Language Coverage Summary

Language	Support Level
C API	✅ Complete (baseline)
C++	✅ Excellent - full coverage of analyzed APIs
.NET (C#)	✅ Excellent - full coverage of analyzed APIs
Go	✅ Excellent - full coverage including recent additions
TypeScript	✅ Excellent - full coverage with modern types
OCaml	✅ Excellent - full coverage of analyzed APIs
Python	⚠️ Good - missing congruence closure APIs
Java	⚠️ Good - missing congruence closure APIs

---

Medium Priority Issues

1. Python Missing Congruence Closure APIs

What's missing: Congruence closure introspection APIs added in recent Z3 versions

C API functions:

• Z3_solver_congruence_root(c, s, a)
• Z3_solver_congruence_next(c, s, a)
• Z3_solver_congruence_explain(c, s, a, b)

Available in: C, C++, C#, Go, OCaml, TypeScript
Missing in: Python

Details:
These APIs allow introspection into the congruence closure computed by the solver, which is useful for:

• Understanding why the solver concluded two terms are equal
• Iterating through equivalence classes
• Debugging solver behavior
• Building explanation/proof systems

Implementation notes:

• C++ exposes as: solver::congruence_root(), solver::congruence_next(), solver::congruence_explain()
• C# exposes as: Solver.CongruenceRoot(), Solver.CongruenceNext(), Solver.CongruenceExplain()
• Go exposes as: (*Solver).CongruenceRoot(), (*Solver).CongruenceNext(), (*Solver).CongruenceExplain()
• TypeScript exposes as: solver.congruenceRoot(), solver.congruenceNext(), solver.congruenceExplain()
• OCaml exposes as: Solver.congruence_root, Solver.congruence_next, Solver.congruence_explain

Suggested fix:
Add methods to Python's Solver class in src/api/python/z3/z3.py:

def congruence_root(self, a):
    """Return the congruence closure root of term a.
    
    Terms eliminated during pre-processing are not visible to congruence closure.
    """
    return _to_expr_ref(Z3_solver_congruence_root(self.ctx.ref(), self.solver, a.as_ast()), self.ctx)

def congruence_next(self, a):
    """Return next element in the congruence class of term a.
    
    Congruence classes form a circular list.
    """
    return _to_expr_ref(Z3_solver_congruence_next(self.ctx.ref(), self.solver, a.as_ast()), self.ctx)

def congruence_explain(self, a, b):
    """Return an explanation for why terms a and b are congruent.
    
    Returns an expression justifying the congruence.
    """
    return _to_expr_ref(Z3_solver_congruence_explain(self.ctx.ref(), self.solver, a.as_ast(), b.as_ast()), self.ctx)

Files to modify: src/api/python/z3/z3.py (Solver class)

Verified: Checked codebase on 2026-02-20 - confirmed missing

---

2. Java Missing Congruence Closure APIs

What's missing: Same congruence closure APIs as Python issue above

C API functions:

• Z3_solver_congruence_root(c, s, a)
• Z3_solver_congruence_next(c, s, a)
• Z3_solver_congruence_explain(c, s, a, b)

Available in: C, C++, C#, Go, OCaml, TypeScript
Missing in: Java

Suggested fix:
Add methods to Solver class in src/api/java/Solver.java:

/**
 * Retrieve the congruence closure root of term t.
 * Terms eliminated during pre-processing are not visible to congruence closure.
 * `@param` t The term to find the congruence root for
 * `@return` The root of the congruence class containing t
 */
public (R extends Sort) Expr(R) congruenceRoot(Expr(R) t) {
    checkContextMatch(t);
    return (Expr(R)) Expr.create(
        getContext(),
        Native.solverCongruenceRoot(getContext().nCtx(), getNativeObject(), t.getNativeObject())
    );
}

/**
 * Retrieve next element in the congruence class of term t.
 * Congruence classes form a circular list.
 * `@param` t The term to find the next congruent term for
 * `@return` The next term in the congruence class
 */
public (R extends Sort) Expr(R) congruenceNext(Expr(R) t) {
    checkContextMatch(t);
    return (Expr(R)) Expr.create(
        getContext(),
        Native.solverCongruenceNext(getContext().nCtx(), getNativeObject(), t.getNativeObject())
    );
}

/**
 * Explain why terms a and b are congruent.
 * `@param` a First term
 * `@param` b Second term  
 * `@return` An expression justifying the congruence between a and b
 */
public (R extends Sort) Expr(R) congruenceExplain(Expr(R) a, Expr(R) b) {
    checkContextMatch(a);
    checkContextMatch(b);
    return (Expr(R)) Expr.create(
        getContext(),
        Native.solverCongruenceExplain(
            getContext().nCtx(),
            getNativeObject(),
            a.getNativeObject(),
            b.getNativeObject()
        )
    );
}

Files to modify:

• src/api/java/Solver.java (add methods)
• src/api/java/Native.java (add JNI declarations - check if already present)

Verified: Checked codebase on 2026-02-20 - confirmed missing

---

Progress Tracker

APIs analyzed so far: ~25/~200 (12.5%)

Completed in this run ✅

• Context creation and configuration
• Solver core APIs
• Solver diagnostic APIs
• Solver congruence closure APIs
• Solver file I/O APIs
• BitVector extension/rotation
• Array theory basics

Next areas to analyze 📋

Priority for next run:

1. Quantifier APIs - mk_forall, mk_exists, quantifier patterns
2. Floating-point APIs - FP sorts, operations, rounding modes
3. Datatype APIs - Constructor/accessor generation
4. Tactic APIs - Tactic composition, probes
5. Simplifier APIs - New simplification framework

Future areas 🔮

• Model APIs (evaluation, function graphs)
• Optimize APIs (objectives, Pareto fronts)
• Fixedpoint APIs (Datalog extensions)
• Sequence/String theory
• Special relations APIs

---

Observations

Positive Findings ✅

1. Core solver APIs have excellent coverage - All 7 languages support push/pop/check/assert/get_model
2. Diagnostic APIs well-supported - units(), trail(), statistics() available in all languages
3. File I/O APIs consistent - from_file() and from_string() present across all bindings
4. BitVector APIs complete - All extension and rotation operations available in all languages
5. Recent additions like Go and TypeScript are up-to-date - These newer bindings include the latest APIs like congruence closure

Areas for Improvement ⚠️

1. Congruence closure APIs - Python and Java bindings haven't been updated with these newer APIs (added ~2023-2024)
2. API documentation consistency - Some languages have better inline documentation than others

Naming Conventions 📝

The analysis confirms consistent naming patterns across languages:

• C: Z3_solver_operation_name
• C++: solver::operation_name() (snake_case methods)
• Python: Solver.operation_name() (snake_case methods)
• Java: Solver.operationName() (camelCase methods)
• C#: Solver.OperationName() (PascalCase methods)
• Go: (*Solver).OperationName() (PascalCase methods)
• TypeScript: solver.operationName() (camelCase methods)
• OCaml: Solver.operation_name (snake_case functions)

---

Methodology

This analysis used a combination of:

1. Direct C API inspection - src/api/z3_api.h as baseline
2. Serena language server - For Java, Python, TypeScript, C# analysis
3. grep/glob searches - For C++, Go, OCaml file inspection
4. Cross-referencing - Verified each API across all 7 language bindings

---

Next Steps

This is an ongoing effort. The next run will:

1. ✅ Re-verify the 2 cached issues from this run
2. 🔍 Analyze 3-5 more API families (Quantifiers, FP, Datatypes)
3. 📊 Update cumulative statistics
4. 🎯 Continue systematic coverage of the ~200 total APIs

Cache updated: Progress saved to /tmp/gh-aw/cache-memory/api-coherence-progress.json

---

This report was generated automatically by the API Coherence Checker agent on 2026-02-20.

AI generated by API Coherence Checker

• expires on Feb 27, 2026, 3:29 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-27T15:29:42.246Z.

Closed by Workflow