[API Coherence] Report for March 5, 2026 - BitVector/Array/FPA APIs

[github-actions[bot]]

Summary

This run analyzed 5 API families across 8 language bindings (Java, .NET, C++, Python, TypeScript, OCaml, Go, Rust), with a focus on:

• BitVector operations (Z3_mk_bv*, rotate, extend, extract)
• Array theory APIs (Z3_mk_select, Z3_mk_store, Z3_mk_array_ext)
• Floating-point APIs (Z3_mk_fpa_*)
• Continued monitoring of Solver and Optimize APIs

Statistics

• APIs analyzed in this run: BitVector (40+ operations), Array (8 operations), Floating-point (30+ operations)
• Total API families covered so far: 5/~20 (25%)
• Languages analyzed: 8 (Java, .NET, C++, Python, TypeScript, OCaml, Go, Rust)
• Previously cached issues now resolved: 4 ✅
• Remaining open issues: 9
• New issues discovered: 2

---

🎉 Resolution Updates

Great progress! The following cached issues from the previous run (Feb 24, 2026) have been resolved:

✅ 1. Solver.toDimacs() - FULLY RESOLVED

All languages now support converting solvers to DIMACS format:

• Previously missing: Java, .NET, TypeScript, Go, OCaml
• Now implemented: ✅ All languages have it
  • Java: Solver.toDimacs(boolean includeNames) - src/api/java/Solver.java:587
  • .NET: Solver.ToDimacs(bool includeNames) - src/api/dotnet/Solver.cs:658
  • TypeScript: Solver.dimacs(includeNames: boolean) - src/api/js/src/high-level/high-level.ts:2151
  • Go: Solver.ToDimacs(includeNames bool) - src/api/go/solver.go:398
  • OCaml: Solver.to_dimacs - src/api/ml/z3.ml:1967

✅ 2. TypeScript Optimize.getLower()/getUpper() - RESOLVED

• Previously: TypeScript users couldn't retrieve optimization objective bounds
• Now: Both methods implemented - src/api/js/src/high-level/high-level.ts:2388-2394

✅ 3. TypeScript Optimize APIs - RESOLVED

• Previously missing: fromFile(), unsatCore(), objectives(), reasonUnknown()
• Now: All implemented in TypeScript src/api/js/src/high-level/high-level.ts:2396-2410

✅ 4. TypeScript Optimize.translate() - RESOLVED

• Now available: src/api/js/src/high-level/high-level.ts:2413

---

Progress Tracking

Completed API Families (5/~20)

1. ✅ Solver APIs (Z3_solver_*)
2. ✅ Optimize APIs (Z3_optimize_*)
3. ✅ BitVector operations (Z3_mk_bv*, rotate, extend)
4. ✅ Array theory APIs (Z3_mk_select, Z3_mk_store, Z3_mk_array_*)
5. ✅ Floating-point APIs (Z3_mk_fpa_*)

Next Run (Planned)

6. Quantifier APIs (Z3_mk_forall, Z3_mk_exists, Z3_mk_lambda)
7. Fixedpoint APIs (Z3_fixedpoint_*)
8. Datatype APIs (Z3_mk_datatype, Z3_mk_constructor)
9. Tactic APIs (Z3_mk_tactic, Z3_tactic_*)
10. AST manipulation APIs (Z3_substitute, Z3_update_term)

---

Medium Priority Issues

1. Z3_solver_translate missing in Go, Rust

What: Move solver to a different context (useful for multi-context applications)
Available in: Python, Java, .NET, C++, OCaml, TypeScript
Missing in: Go, Rust
Fix:

• Go: Add Solver.Translate(target *Context) *Solver method in src/api/go/solver.go
• Rust: Add Solver::translate(&self, target: &Context) -> Solver<'_> method in z3/src/solver.rs

2. Z3_solver_get_proof missing in Go

What: Retrieve proof object after UNSAT result (critical for proof-carrying code)
Available in: Python, Java, .NET, C++, OCaml, Rust, TypeScript
Missing in: Go
Fix: Add Solver.Proof() *AST method in src/api/go/solver.go, calling Z3_solver_get_proof

3. Z3_solver_add_simplifier missing in Java, Rust

What: Add a simplifier to solver's preprocessor (improves performance on complex formulas)
Available in: Python, .NET, C++, OCaml, TypeScript, Go
Missing in: Java, Rust
Fix:

• Java: Add Solver.addSimplifier(Simplifier s) method in src/api/java/Solver.java
• Rust: Add Solver::add_simplifier(&self, simplifier: &Simplifier) in z3/src/solver.rs

4. Z3_optimize_translate missing in OCaml, Go, Rust

What: Move optimize instance to a different context
Available in: Python, Java, .NET, C++, TypeScript
Missing in: OCaml, Go, Rust
Fix:

• OCaml: Add Optimize.translate function in src/api/ml/z3.ml
• Go: Add Optimize.Translate(target *Context) *Optimize in src/api/go/optimize.go
• Rust: Add Optimize::translate(&self, target: &Context) -> Optimize<'_> in z3/src/optimize.rs

5. Z3_mk_array_ext missing in TypeScript, Go

What: Array extensionality - returns an index where two arrays differ (very useful for debugging array constraints)
C API: Z3_mk_array_ext(ctx, a1, a2) returns an index i such that a1[i] != a2[i]
Available in: Python, Java, .NET, C++, OCaml, Rust
Missing in: TypeScript, Go
Fix:

• TypeScript: Add arrayExt(a1: Array, a2: Array): Expr to Context class
• Go: Add MkArrayExt(a1, a2 *AST) *AST method

6. Rust z3 crate missing many Solver/Optimize APIs

What: The Rust high-level bindings lack several advanced solver features
Missing APIs:

• Solver::interrupt() - cancel ongoing check() call
• Solver::cube() - get partial model as cube
• Solver::get_trail() - get solver trail (assigned literals)
• Solver::congruence_*() - congruence closure queries
• Solver::solve_for() - solve w.r.t. specific variables
• Solver::set_initial_value() - set initial value hint
• Solver::add_simplifier() - add preprocessor
• Solver::from_file() - load from SMT2 file
• Solver::register_on_clause() - clause callback
• Optimize::from_file() - load from file

Available in: Python, Java, .NET, C++, OCaml, Go, TypeScript (most of these)
Missing in: Rust (external crate: prove-rs/z3.rs)
Fix: The Rust bindings maintainers should add wrappers for these in z3/src/solver.rs and z3/src/optimize.rs

---

Low Priority Issues

7. Z3_solver_register_on_clause missing in most languages

What: Register callback for learned clauses (advanced feature for CDCL integration)
Available in: Python, .NET, C++
Missing in: TypeScript, Go, Java, OCaml, Rust
Priority: Low - very advanced feature, rarely used
Note: Requires callback mechanism support in each language

8. Java BitVecExpr missing convenience methods

What: Java lacks instance methods for common bit-vector operations
Issue: Operations like rotateLeft(), rotateRight(), signExt(), zeroExt() must be called as ctx.MkBVRotateLeft(expr, n) instead of expr.rotateLeft(n)
Available as instance methods in: Python, TypeScript, .NET
Missing in: Java (only available via Context.Mk* static methods)
Fix: Add convenience methods to src/api/java/BitVecExpr.java:

public BitVecExpr rotateLeft(int count) {
    return getContext().MkBVRotateLeft(count, this);
}
public BitVecExpr rotateRight(int count) {
    return getContext().MkBVRotateRight(count, this);
}
public BitVecExpr signExt(int count) {
    return getContext().MkSignExt(count, this);
}
public BitVecExpr zeroExt(int count) {
    return getContext().MkZeroExt(count, this);
}

9. Rust z3-sys missing FFI bindings for newer C APIs

What: The low-level FFI layer (z3-sys) doesn't expose some newer C API functions
Missing bindings: Z3_solver_interrupt, Z3_solver_add_simplifier, Z3_solver_get_trail, Z3_solver_register_on_clause, Z3_solver_congruence_*, Z3_solver_solve_for, Z3_solver_set_initial_value
Impact: Even if high-level Rust bindings wanted to add these, they can't without FFI access
Fix: Update z3-sys/src/lib.rs to include these C function declarations (they're likely auto-generated from z3_api.h)

---

Observations

BitVector Operations

All languages have good coverage of basic BitVector operations (add, sub, mul, div, shifts, logical ops). Key observations:

• ✅ Python: Full coverage with functions like RotateLeft(), RotateRight(), SignExt(), ZeroExt()
• ✅ TypeScript: Excellent - instance methods on BitVec(Bits) class
• ✅ .NET: Complete via Context.MkBVRotateLeft(), MkSignExt(), etc., plus overloaded variants
• ✅ C++: Full coverage with zext(), sext(), inline helper functions
• ⚠️ Java: All operations available but only via Context.Mk* methods, not as instance methods

Array Theory APIs

Good consistency across languages for core operations (select, store, const_array):

• ✅ All languages support Z3_mk_select and Z3_mk_store
• ⚠️ Z3_mk_array_ext missing in TypeScript and Go (medium priority - useful for debugging)
• ✅ Z3_mk_array_default available in all checked languages

Floating-Point APIs

Not deeply analyzed in this run, but spot checks show good coverage in Python, C++, .NET, Java. Will analyze more thoroughly in a future run.

---

Developer Experience Notes

1. TypeScript has made excellent progress - most issues from the previous run are now resolved
2. Go bindings are mostly complete but missing a few solver APIs (translate, get_proof)
3. Rust bindings (external repo) lag behind - maintainers should prioritize catching up with newer C APIs
4. Java has full functionality but could benefit from ergonomic improvements (instance methods on expr classes)

---

Recommendations

For Z3 Maintainers

1. Go: Add Solver.Translate() and Solver.Proof() - straightforward C API wrappers
2. Java: Consider adding convenience methods to BitVecExpr for better ergonomics

For Rust z3.rs Maintainers (prove-rs/z3.rs)

1. Priority: Update z3-sys FFI bindings to expose newer C API functions
2. Priority: Add missing Solver/Optimize methods in high-level wrapper (interrupt, cube, trail, etc.)
3. Consider syncing with Z3's official release cycle to stay current

For Future Analysis

Next run should focus on:

• Quantifier APIs (forall, exists, lambda)
• Fixedpoint APIs
• Datatype construction APIs
• Tactic framework APIs

AI generated by API Coherence Checker

• expires on Mar 12, 2026, 11:40 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-12T23:40:47.599Z.

Closed by Workflow