[API Coherence] Run #2 - BitVector, Floating-Point, Array, Quantifier APIs

[github-actions[bot]]

Summary

Run Date: February 28, 2026
Run Number: 2 of ongoing systematic analysis
APIs Analyzed This Run:

• BitVector operations (39 core functions + 8 overflow/underflow checks)
• Floating-point APIs (81 functions)
• Array theory APIs (10 functions)
• Quantifier APIs (10 functions)

Statistics:

• Total functions checked: ~150 across 8 languages
• Previously cached issues: 10
• Issues resolved since last run: 8 🎉
• New issues found: 2
• Total open issues: 8

🎉 Resolved Issues (Since Last Run on Feb 24)

The following issues from the previous run have been resolved and are now closed:

High Priority - TypeScript Optimize API (2 issues)

1. ✅ TypeScript Optimize getLower()/getUpper() - Can now retrieve optimization results

   • Found: getLower() and getUpper() methods in src/api/js/src/high-level/high-level.ts:4838,4842

2. ✅ TypeScript Optimize missing fromFile/unsatCore/objectives/reasonUnknown() - Complete optimization API

   • Found: All methods now present in src/api/js/src/high-level/high-level.ts

Medium Priority - Solver APIs (6 issues)

3. ✅ Java missing toDimacs()

   • Found: toDimacs(boolean includeNames) in src/api/java/Solver.java

4. ✅ Java missing addSimplifier()

   • Found: addSimplifier(Simplifier simplifier) in src/api/java/Solver.java

5. ✅ .NET missing ToDimacs()

   • Found: ToDimacs(bool includeNames = true) in src/api/dotnet/Solver.cs

6. ✅ TypeScript missing translate()

   • Found: translate() method in TypeScript Solver class

7. ✅ TypeScript missing getProof()

   • Found: getProof() method in TypeScript Solver class

8. ✅ Go missing Translate(), GetProof(), AddSimplifier()

   • Found: All three methods in src/api/go/solver.go

Medium Priority - Optimize APIs (1 issue)

9. ✅ Go missing Optimize.Translate()
   • Found: Translate(target *Context) in src/api/go/optimize.go

Medium Priority - On-Clause Callbacks (1 issue)

10. ✅ TypeScript missing registerOnClause()
    • Found: Full implementation with WASM callback infrastructure in src/api/js/src/high-level/high-level.ts

Great progress! 8 issues resolved, showing active API development across Java, .NET, TypeScript, and Go bindings.

---

📊 Progress Tracker

• APIs analyzed so far: 6 of ~20 families (30%)
• Completed:
  • ✅ Solver APIs (Z3_solver_*)
  • ✅ Optimize APIs (Z3_optimize_*)
  • ✅ BitVector operations (Z3_mk_bv*)
  • ✅ Floating-point APIs (Z3_mk_fpa_*)
  • ✅ Array theory APIs (Z3_mk_select, Z3_mk_store, etc.)
  • ✅ Quantifier APIs (Z3_mk_forall, Z3_mk_exists, Z3_mk_lambda)
• Next run: Fixedpoint APIs, Datatype APIs, Proof APIs, Tactic APIs

---

🔴 Open Issues (Unresolved)

Medium Priority

1. Go: Missing 8 BitVector Overflow/Underflow Check Functions

NEW in this run

What's missing: BitVector arithmetic overflow/underflow predicates
Available in: C, C++, Python, Java, .NET, TypeScript, OCaml
Missing in: Go, Rust

Missing functions:

• Z3_mk_bvadd_no_overflow - Check if addition overflows
• Z3_mk_bvadd_no_underflow - Check if signed addition underflows
• Z3_mk_bvsub_no_overflow - Check if subtraction overflows
• Z3_mk_bvsub_no_underflow - Check if signed subtraction underflows
• Z3_mk_bvsdiv_no_overflow - Check if signed division overflows
• Z3_mk_bvneg_no_overflow - Check if negation overflows
• Z3_mk_bvmul_no_overflow - Check if multiplication overflows
• Z3_mk_bvmul_no_underflow - Check if signed multiplication underflows

C API reference: src/api/z3_api.h:3172-3249
Target file: src/api/go/bitvec.go

Suggested implementation (Go):

func (c *Context) MkBVAddNoOverflow(t1, t2 *Expr, isSigned bool) *Expr {
    return &Expr{
        ctx: c,
        ptr: C.Z3_mk_bvadd_no_overflow(c.ptr, t1.ptr, t2.ptr, C.bool(isSigned)),
    }
}

func (c *Context) MkBVAddNoUnderflow(t1, t2 *Expr) *Expr {
    return &Expr{
        ctx: c,
        ptr: C.Z3_mk_bvadd_no_underflow(c.ptr, t1.ptr, t2.ptr),
    }
}
// ... similar for other 6 functions

Why it matters: These predicates are essential for formal verification of arithmetic-heavy code, where detecting overflow/underflow bugs is critical for correctness and security.

---

2. Rust: Missing 8 BitVector Overflow/Underflow Check Functions

NEW in this run

Same functions as issue #1 above.

Target: z3.rs/z3/src/ (external repo: https://github.com/prove-rs/z3.rs)
Dependency: Also requires FFI bindings in z3-sys crate first

Note: This is an external repository. Consider opening an issue at https://github.com/prove-rs/z3.rs/issues

---

3. Go: Missing Z3_solver_to_dimacs_string

What's missing: Export solver constraints to DIMACS format (CNF)
Available in: Python, C++, Java, .NET, TypeScript, OCaml
Missing in: Go, Rust

C API: Z3_solver_to_dimacs_string(c, s, include_names)
Reference: src/api/z3_api.h
Target file: src/api/go/solver.go

Suggested fix:

func (s *Solver) ToDimacs(includeNames bool) string {
    cStr := C.Z3_solver_to_dimacs_string(s.ctx.ptr, s.ptr, C.bool(includeNames))
    return C.GoString(cStr)
}

---

4. Rust: Missing Z3_solver_to_dimacs_string

Same as issue #3 above.

Target: z3.rs/z3/src/solver.rs

---

5. Rust: Missing Z3_solver_translate

What's missing: Translate solver from one context to another
Available in: Python, Java, .NET, C++, OCaml, TypeScript, Go
Missing in: Rust

C API: Z3_solver_translate(source_ctx, s, target_ctx)
Target: z3.rs/z3/src/solver.rs

---

6. Go, Java, Rust: Missing Z3_solver_register_on_clause

What's missing: Register callback for learned clauses during solving
Available in: Python, .NET, C++, OCaml, TypeScript
Missing in: Go, Java, Rust

C API: Z3_solver_register_on_clause(c, s, user_context, on_clause_eh)
Use case: Advanced SAT solver integration, incremental learning

Note: Requires language-specific callback infrastructure (function pointers, FFI closures)

---

7. TypeScript, OCaml, Rust: Missing Z3_optimize_translate

What's missing: Translate optimizer from one context to another
Available in: Python, Java, .NET, C++, Go
Missing in: TypeScript, OCaml, Rust

C API: Z3_optimize_translate(source_ctx, o, target_ctx)

---

8. Rust: Many Solver/Optimize APIs Missing

The Rust z3 crate is missing numerous APIs available in other high-level bindings:

Solver APIs missing:

• interrupt() - Interrupt ongoing solve
• cube() - Get cube (partial model)
• get_trail() - Get solver trail
• congruence_*() - Congruence closure queries
• solve_for() - Solve with specific variables
• set_initial_value() - Provide initial value hint
• Plus issues Fixed exponentiation in examples/python/complex/complex.py. #2, fix mix of tab and space in mk_util.py #4, Missing code in complex.py example #5, Enhancement: Use operator overloading in the .NET API #6 above

Optimize APIs missing:

• translate() - Context translation
• Plus general solver gaps

Note: External repository at https://github.com/prove-rs/z3.rs. Many of these may require FFI additions in z3-sys first.

---

🟢 APIs With Good Coherence

The following API families showed excellent cross-language coherence with no significant gaps:

✅ Floating-Point APIs (81 functions)

All major FP operations well-covered across all languages:

• Rounding modes (RNE, RNA, RTP, RTN, RTZ)
• Sort constructors (half, single, double, quadruple, custom)
• Arithmetic (add, sub, mul, div, fma, sqrt, rem)
• Comparisons (lt, gt, le, ge, eq)
• Predicates (isNaN, isInf, isZero, isNormal, isSubnormal, isNegative, isPositive)
• Conversions (to/from IEEE bit-vector, int, real)

Checked across: Python, Java, .NET, C++, TypeScript, Go, OCaml, Rust ✅

✅ Array Theory APIs (10 functions)

All major array operations well-covered:

• mk_array_sort, mk_array_sort_n - Array type constructors
• mk_select, mk_select_n - Array read (multi-dimensional)
• mk_store, mk_store_n - Array write (multi-dimensional)
• mk_const_array - Constant arrays
• mk_array_default - Get default value
• mk_array_ext - Array extensionality
• mk_as_array - Convert function to array

Checked across: Python, Java, .NET, C++, TypeScript, Go, OCaml, Rust ✅

✅ Quantifier APIs (10 functions)

All major quantifier operations well-covered:

• mk_forall, mk_forall_const - Universal quantification
• mk_exists, mk_exists_const - Existential quantification
• mk_lambda, mk_lambda_const - Lambda expressions
• mk_quantifier, mk_quantifier_ex - Generic quantifier construction
• mk_quantifier_const, mk_quantifier_const_ex - With bound constants

Checked across: Python, Java, .NET, C++, TypeScript, Go, OCaml ✅

---

📋 Methodology

Systematic Approach:

1. Selected 4 API families (BitVector, FP, Array, Quantifier) totaling ~150 functions
2. Identified baseline from C API (z3_api.h, z3_fpa.h)
3. Checked each language binding using:
   • Serena (for Java, Python, TypeScript, C#)
   • grep/glob (for C++, OCaml, Go)
   • Clone + grep (for external Rust repo)
4. Compared naming conventions, parameter types, and return types
5. Re-verified all 10 cached issues from previous run before reporting
6. Documented gaps with specific file locations and function signatures

Languages Analyzed:

• ✅ C (baseline API)
• ✅ C++ (src/api/c++/z3++.h)
• ✅ Python (src/api/python/z3/z3.py)
• ✅ Java (src/api/java/*.java)
• ✅ .NET/C# (src/api/dotnet/*.cs)
• ✅ TypeScript/JavaScript (src/api/js/src/high-level/)
• ✅ OCaml (src/api/ml/*.ml, *.mli)
• ✅ Go (src/api/go/*.go)
• ✅ Rust (external: github.com/prove-rs/z3.rs)

---

🎯 Recommendations Priority

For Z3 maintainers:

High Impact:

1. ✅ TypeScript Optimize API - RESOLVED! No action needed.

Medium Impact:
2. Go BitVector overflow/underflow - Add 8 missing functions to src/api/go/bitvec.go

• Straightforward CGO wrappers
• Important for verification use cases
• Pattern: Follow existing MkBVAdd, MkBVMul implementations

3. Go Solver.ToDimacs() - Add DIMACS export to Go
   • Simple string-returning wrapper
   • Useful for SAT solver integration

External Coordination:
4. Rust bindings - Consider engaging with prove-rs/z3.rs maintainers

• Multiple APIs missing (overflow checks, solver APIs, optimize APIs)
• May need FFI additions in z3-sys first
• Could provide guidance or contribute PRs

Lower Priority (Advanced Features):
5. registerOnClause callbacks - Missing in Go, Java, Rust

• Complex: Requires callback infrastructure
• Advanced feature with smaller user base
• Consider demand before implementing

---

📌 Next Analysis Run

Planned for next run:

• Fixedpoint APIs (Z3_fixedpoint_*)
• Datatype APIs (Z3_mk_datatype, constructors, accessors)
• Proof APIs (Z3_get_proof, Z3_proof_*)
• Tactic APIs (Z3_mk_tactic, combinators)
• Interpolation APIs (if available)

Expected completion: Run #3 will bring us to ~50% coverage of the total API surface.

---

📝 Notes

• Cache verified: All 10 previously cached issues were re-verified against current codebase before reporting
• 8 resolved issues removed from cache - excellent progress since Feb 24!
• Rust repo: External at github.com/prove-rs/z3.rs - issues noted but outside direct Z3 repo scope
• No style/naming issues - This report focuses only on missing functionality, not conventions
• Automatic closure: This discussion will auto-close when new reports are posted

---

API Coherence Checker - Automated systematic analysis
Run frequency: Weekly or on-demand
Questions? Comment below!

AI generated by API Coherence Checker

• expires on Mar 7, 2026, 11:18 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-07T23:18:38.187Z.

Closed by Workflow