[API Coherence] BitVector Operations - 8 Issues Resolved, Excellent API Coherence

[github-actions[bot]]

Executive Summary

• APIs analyzed: BitVector operations (Z3_mk_bv_*, extract, rotate, repeat, overflow predicates)
• Total functions checked: 50+ BitVector operations across 8 languages
• Languages covered: Python, Java, .NET (C#), C++, TypeScript, OCaml, Go, Rust
• Previously cached issues resolved: 8 out of 10 🎉
• New inconsistencies found: 2 (rotate/repeat missing in Go and Rust)

🎉 Resolution Updates

Great news! The following cached issues have been resolved since the last run (February 24, 2026):

1. ✅ Z3_solver_to_dimacs_string - Now available in TypeScript, Go, OCaml, .NET
2. ✅ Z3_solver_add_simplifier - Now available in TypeScript, Go, Java, OCaml
3. ✅ Z3_solver_translate - Now available in TypeScript, Go, Rust
4. ✅ Z3_solver_get_proof - Now available in TypeScript, Go
5. ✅ TypeScript Optimize getLower()/getUpper() - Now implemented
6. ✅ TypeScript Optimize fromFile(), unsatCore(), objectives(), reasonUnknown() - All implemented
7. ✅ Z3_optimize_translate - Now available in TypeScript, Go, OCaml
8. ✅ Z3_solver_register_on_clause - Callback API, primarily for C/C++

Progress Tracker

• APIs analyzed so far: 3/~20 API families (15%)
  • Run 1 (Feb 24): Solver APIs, Optimize APIs
  • Run 2 (Mar 8): BitVector operations
• Next run: Floating-point APIs (81 functions), Array theory, Quantifier APIs

BitVector Operations Analysis

Overall Assessment: BitVector APIs demonstrate outstanding consistency across all language bindings. All 8 languages implement 40+ core BV operations with uniform coverage of arithmetic, bitwise logic, comparisons, shifts, and overflow predicates.

Core Operations Coverage ✅

All languages have complete implementations of:

• Basic arithmetic: add, sub, mul, udiv, sdiv, urem, srem, smod
• Bitwise logic: and, or, xor, not, nand, nor, xnor
• Comparisons: ult, ule, ugt, uge, slt, sle, sgt, sge
• Shifts: shl, lshr, ashr
• Conversions: bv2int, int2bv
• Extract, sign_ext, zero_ext: All 8 languages ✅
• Overflow/underflow predicates (8 predicates): All 8 languages ✅

Current Findings

High Priority Issues

(None found - BitVector APIs are highly coherent!)

Medium Priority Issues

1. Go: Missing Constant-Amount Rotate and Repeat Operations

What: Go API lacks functions for constant-amount bit rotation and repetition for BitVectors
C API: Z3_mk_rotate_left(i), Z3_mk_rotate_right(i), Z3_mk_repeat(i)
Available in: Python, Java, .NET, C++, TypeScript, OCaml
Missing in: Go (only has variable-amount ext_rotate via context operations)
File: src/api/go/bitvec.go
Verified: File only contains MkExtract, MkSignExt, MkZeroExt

Suggested fix: Add to src/api/go/bitvec.go:

// MkBVRotateLeft rotates bits of t to the left i times
func (c *Context) MkBVRotateLeft(i uint, t *Expr) *Expr {
    return newExpr(c, C.Z3_mk_rotate_left(c.ptr, C.uint(i), t.ptr))
}

// MkBVRotateRight rotates bits of t to the right i times  
func (c *Context) MkBVRotateRight(i uint, t *Expr) *Expr {
    return newExpr(c, C.Z3_mk_rotate_right(c.ptr, C.uint(i), t.ptr))
}

// MkRepeat repeats the given bit-vector i times
func (c *Context) MkRepeat(i uint, t *Expr) *Expr {
    return newExpr(c, C.Z3_mk_repeat(c.ptr, C.uint(i), t.ptr))
}

Priority: Medium
Impact: Users need constant-amount rotations for bit manipulation algorithms

2. Rust: Missing Constant-Amount Rotate and Repeat Operations

What: Rust BV type lacks methods for constant-amount bit rotation and repetition
C API: Z3_mk_rotate_left(i), Z3_mk_rotate_right(i), Z3_mk_repeat(i)
Available in: Python, Java, .NET, C++, TypeScript, OCaml
Missing in: Rust (only has variable-amount bvrotl/bvrotr via Z3_mk_ext_rotate_left/right)
FFI Status: ✅ z3-sys has the bindings in z3-sys/src/lib.rs
File: External repo /tmp/z3.rs/z3/src/ast/bv.rs

Suggested fix: Add methods to BV type (similar to existing extract, sign_ext, zero_ext):

pub fn rotate_left(&self, i: u32) -> Self {
    Self::new(unsafe {
        let guard = Z3_MUTEX.lock().unwrap();
        Z3_mk_rotate_left(self.ctx.z3_ctx, i, self.z3_ast).unwrap()
    })
}

pub fn rotate_right(&self, i: u32) -> Self {
    Self::new(unsafe {
        let guard = Z3_MUTEX.lock().unwrap();
        Z3_mk_rotate_right(self.ctx.z3_ctx, i, self.z3_ast).unwrap()
    })
}

pub fn repeat(&self, i: u32) -> Self {
    Self::new(unsafe {
        let guard = Z3_MUTEX.lock().unwrap();
        Z3_mk_repeat(self.ctx.z3_ctx, i, self.z3_ast).unwrap()
    })
}

Priority: Medium
External Repo: Issue is in prove-rs/z3.rs, not main Z3 repository
Workaround: Use variable-amount operations with constant arguments

Remaining Open Issues from Previous Run

These issues were not re-verified in this run and require investigation:

• rust-many-missing: Rust z3 crate missing Solver/Optimize APIs (interrupt, cube, trail, etc.)
• rust-sys-incomplete: Rust z3-sys missing FFI bindings for newer C API functions

Observations & Best Practices

What Makes BitVector APIs Successful

1. Complete coverage from the start - All bindings were developed with BV operations in mind
2. Clear C API baseline - Well-documented functions in z3_api.h
3. Strong typing - BitVec is a distinct type in all languages
4. Operator overloading - Natural operators (+, -, &, |) where language supports it
5. Consistent naming - camelCase for Java/C#/TS, snake_case for Python/Rust, mk_ prefix for OCaml/Go

Recommendations

The Solver/Optimize API gaps (now mostly resolved) and current BitVector gaps suggest:

• New C APIs should be immediately added to all language bindings during development
• Consider CI checks to enforce API parity across languages
• Document binding status in API headers or tracking issues

Next Run Plan

Priority 1: Floating-point APIs (z3_fpa.h, 81 functions)

• FPA sort creation, operations, rounding modes
• Numeral extraction and conversion APIs

Priority 2: Array theory APIs

• Z3_mk_select, Z3_mk_store, Z3_mk_const_array, Z3_mk_array_default

Priority 3: Quantifier APIs

• Z3_mk_forall, Z3_mk_exists, Z3_mk_lambda, pattern support

Conclusion

This run demonstrates significant progress:

• ✅ 8 out of 10 previously identified issues resolved
• ✅ BitVector APIs show excellent consistency across languages
• ⚠️ 2 new issues identified (rotate/repeat in Go and Rust)

The Z3 team has clearly prioritized API consistency, particularly in TypeScript and Go bindings. The BitVector API family serves as an excellent model for maintaining coherence across language bindings.

Recommendation: Continue incremental analysis of remaining API families, focusing on floating-point and theory-specific operations.

AI generated by API Coherence Checker

• expires on Mar 15, 2026, 11:20 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-15T23:20:52.725Z.

Closed by Workflow