[API Coherence] Report for 2026-02-24 - Solver APIs & Optimize APIs

[github-actions[bot]]

Summary

Run #1 — Solver APIs & Optimize APIs

Metric	Value
API families analyzed	2 (Solver, Optimize)
C API functions checked	~55
Languages covered	8 (Python, .NET, C++, Java, TypeScript, Go, OCaml, Rust)
Previously cached issues resolved	0 (first run)
Inconsistencies found	10

---

Progress

• APIs analyzed so far: Solver APIs, Optimize APIs (~2/~20 API families, ~10%)
• Next run targets: BitVector operations, Floating-point APIs, Array theory APIs, Quantifier APIs

---

High Priority Issues

1. TypeScript Optimize — cannot retrieve optimization results (getLower/getUpper missing)

What's missing: The TypeScript Optimize interface exposes maximize(expr) and minimize(expr) methods, but both return void — discarding the handle index returned by the C API. As a result, users have no way to retrieve optimization bounds after calling check(). The C API functions Z3_optimize_get_lower(ctx, opt, idx) and Z3_optimize_get_upper(ctx, opt, idx) are never called from the TypeScript binding.

Available in: Python (lower(obj), upper(obj)), Java (Handle.getLower(), Handle.getUpper()), .NET (Handle.Lower, Handle.Upper), C++ (optimize::upper(), optimize::lower()), Go (GetLower(index), GetUpper(index)), OCaml (get_lower, get_upper)

Missing in: TypeScript/JavaScript

Suggested fix:

1. Change maximize(expr) and minimize(expr) in types.ts to return a numeric handle index (or an opaque Handle object).
2. Add getLower(index: number): Expr(Name) and getUpper(index: number): Expr(Name) to the Optimize(Name) interface.
3. Add corresponding implementations in high-level.ts.
4. Optionally add getLowerAsVector(index: number) and getUpperAsVector(index: number) for boxed/epsilon bounds.

File: src/api/js/src/high-level/types.ts, src/api/js/src/high-level/high-level.ts

Verified: Checked high-level.ts lines 2309–2315 — Z3.optimize_maximize return value is discarded; no optimize_get_lower/optimize_get_upper calls found anywhere in the TypeScript high-level binding.

---

2. TypeScript Optimize — missing utility APIs

What's missing: Several Optimize API methods present in all other languages are absent from the TypeScript Optimize interface:

C API	TypeScript status	Available in
Z3_optimize_from_file	❌ missing	Python, Java, .NET, C++, OCaml, Go
Z3_optimize_get_unsat_core	❌ missing	Python, Java, .NET, C++, Go
Z3_optimize_get_objectives	❌ missing	Python, Java, .NET, C++, Go, OCaml
Z3_optimize_get_reason_unknown	❌ missing	Python, Java, .NET, C++, Go, OCaml

Suggested fix: Add these methods to the Optimize(Name) interface in types.ts and implement them in OptimizeImpl in high-level.ts:

• fromFile(filename: string): void — wraps Z3_optimize_from_file
• unsatCore(): AstVector(Name, Bool<Name)> — wraps Z3_optimize_get_unsat_core
• objectives(): AstVector(Name, Expr<Name)> — wraps Z3_optimize_get_objectives
• reasonUnknown(): string — wraps Z3_optimize_get_reason_unknown

File: src/api/js/src/high-level/types.ts, src/api/js/src/high-level/high-level.ts

---

Medium Priority Issues

3. Z3_solver_to_dimacs_string — missing in Java, .NET, TypeScript, Go, OCaml, Rust

What's missing: Converting a solver's Boolean formula to DIMACS CNF format (used with external SAT solvers).

Available in: Python (Solver.dimacs(include_names=True) at line 7930), C++ (solver::dimacs() at z3++.h:3114)

Missing in: Java, .NET (Solver class; Goal has ToDimacs but not Solver), TypeScript, Go, OCaml, Rust

Suggested fix:

• Java: Add public String toDimacs(boolean includeNames) to Solver.java calling Native.solverToDimacsString(...)
• .NET: Add public string ToDimacs(bool includeNames = true) to Solver.cs calling Native.Z3_solver_to_dimacs_string(...)
• TypeScript: Add dimacs(includeNames?: boolean): string to Solver(Name) interface and implement in high-level.ts
• Go: Add func (s *Solver) Dimacs(includeNames bool) string to solver.go
• OCaml: Add let to_dimacs x include_names = Z3native.solver_to_dimacs_string (gc x) x include_names

C API: Z3_solver_to_dimacs_string(ctx, solver, include_names) in z3_api.h

---

4. Z3_solver_translate — missing in TypeScript, Go, Rust

What's missing: Translating a solver to a different context (needed when working with multiple Z3 contexts).

Available in: Python (Solver.translate(target_ctx) at line 7906), Java (Solver.translate(ctx) at line 564), .NET (Solver.Translate(ctx) at line 591), C++ (solver::solver(solver, translate) constructor, line 2948), OCaml (Solver.translate at line 1956)

Missing in: TypeScript, Go, Rust

Suggested fix:

• TypeScript: Add translate(target: Context(Name)): Solver(Name) to Solver(Name) interface; implement using Z3.solver_translate(ctx, ptr, target.ptr)
• Go: Add func (s *Solver) Translate(target *Context) *Solver to solver.go
• Rust: Add pub fn translate(&self, target: &Context) -> Solver to solver.rs; note Z3_solver_translate is already in z3-sys

---

5. Z3_solver_get_proof — missing in TypeScript, Go

What's missing: Retrieving a proof of unsatisfiability after a solver returns unsat (requires solver with proof generation enabled).

Available in: Python (Solver.proof() at line 7817), Java (Solver.getProof() at line 315), .NET (Solver.Proof at line 478), C++, OCaml (Solver.get_proof at line 1936), Rust (Solver::get_proof())

Missing in: TypeScript, Go

Suggested fix:

• TypeScript: Add proof(): Expr(Name) | null to Solver(Name) interface; implement using Z3.solver_get_proof
• Go: Add func (s *Solver) GetProof() *Expr to solver.go

---

6. Z3_solver_add_simplifier — missing in Java, Go, Rust

What's missing: Attaching a simplifier to the solver to pre-process assertions before solving.

Available in: Python (SolverFor(..., simplifier) pattern), .NET (via constructor), C++ (solver::solver(solver, simplifier) at line 3406), OCaml (Solver.add_simplifier at line 1955), TypeScript (Solver.addSimplifier())

Missing in: Java, Go, Rust

Suggested fix:

• Java: Add public Solver addSimplifier(Simplifier simplifier) to Solver.java
• Go: Add func (s *Solver) AddSimplifier(simplifier *Simplifier) *Solver to solver.go
• Rust: Add pub fn add_simplifier(&self, simplifier: &Simplifier) -> Solver to solver.rs

---

7. Z3_solver_register_on_clause — missing in TypeScript, Go, Java, OCaml, Rust

What's missing: Registering a callback to be notified when the solver derives a new clause (for monitoring/proof logging).

Available in: Python (via OnClause class at line 12117), .NET (via OnClause.cs), C++ (via on_clause class, z3++.h:4601)

Missing in: TypeScript, Go, Java, OCaml, Rust

Suggested fix:

• TypeScript: Add registerOnClause(callback: (proof_hint: Expr(Name), clause: AstVector(Name)) => void): void to the Solver(Name) interface
• Go: Add func (s *Solver) RegisterOnClause(callback func(*Expr, []*Expr)) to solver.go
• Java: Add an OnClause helper class similar to Python's/C#'s implementation
• OCaml: Add let register_on_clause ... binding to z3.ml

---

8. Z3_optimize_translate — missing in TypeScript, OCaml, Go, Rust

What's missing: Translating an Optimize object to a different context.

Available in: Python (check), Java (not found), .NET (not found), C++ (optimize::translate(), z3++.h:3560), Go (not found)

Missing in: TypeScript, OCaml, Go, Rust

Note: This is less widely supported; mainly available in C++ but still an API gap for users who work with multiple contexts.

---

9. Rust z3 crate — broadly missing newer Solver/Optimize APIs

What's missing: The high-level Rust z3 crate is missing many solver diagnostic and advanced APIs that are available in other language bindings. The z3-sys low-level crate also needs updates for some newer C API functions.

Missing from Rust z3 crate Solver:

• interrupt() — Z3_solver_interrupt
• cube() — Z3_solver_cube (z3-sys has it, high-level crate doesn't)
• get_units() / get_non_units() — (z3-sys has get_units; z3 crate doesn't expose either)
• get_trail() — Z3_solver_get_trail
• congruence_root() / congruence_next() / congruence_explain()
• set_initial_value() — Z3_solver_set_initial_value
• add_simplifier() — Z3_solver_add_simplifier
• solve_for() — Z3_solver_solve_for
• from_file() — Z3_solver_from_file
• to_dimacs() — Z3_solver_to_dimacs_string
• translate() — Z3_solver_translate (z3-sys has it; z3 crate doesn't wrap it)

Missing from Rust z3 crate Optimize:

• get_lower() / get_upper()
• from_file() — Z3_optimize_from_file
• translate() — Z3_optimize_translate
• register_model_eh() — Z3_optimize_register_model_eh

Missing from z3-sys (FFI bindings not exposed):

• Z3_solver_interrupt
• Z3_solver_to_dimacs_string
• Z3_solver_add_simplifier
• Z3_solver_get_trail
• Z3_solver_register_on_clause
• Z3_solver_congruence_root / _next / _explain
• Z3_solver_solve_for
• Z3_solver_set_initial_value

Suggested fix: Contributions to https://github.com/prove-rs/z3.rs to update z3-sys FFI bindings and add high-level wrappers.

---

Low Priority Issues

10. Z3_solver_to_dimacs_string inconsistency — .NET has it for Goal but not for Solver

What's missing: .NET's Goal.cs exposes ToDimacs() (line 228) via Z3_goal_to_dimacs_string, but the Solver class has no equivalent for Z3_solver_to_dimacs_string. Users working with SAT problems in Solver must use Goal as a workaround.

---

Comparison Tables

Solver API Coverage Matrix

C API Function	Python	.NET	C++	Java	TypeScript	Go	OCaml	Rust
Z3_solver_check	✅	✅	✅	✅	✅	✅	✅	✅
Z3_solver_assert	✅	✅	✅	✅	✅	✅	✅	✅
Z3_solver_get_model	✅	✅	✅	✅	✅	✅	✅	✅
Z3_solver_get_proof	✅	✅	✅	✅	❌	❌	✅	✅
Z3_solver_translate	✅	✅	✅	✅	❌	❌	✅	❌
Z3_solver_to_dimacs_string	✅	❌	✅	❌	❌	❌	❌	❌
Z3_solver_add_simplifier	✅	✅	✅	❌	✅	❌	✅	❌
Z3_solver_interrupt	✅	✅	✅	✅	✅	✅	✅	❌
Z3_solver_cube	✅	✅	✅	✅	✅	✅	✅	❌
Z3_solver_get_units	✅	✅	✅	✅	✅	✅	✅	❌
Z3_solver_get_non_units	✅	✅	✅	✅	✅	✅	✅	❌
Z3_solver_get_trail	✅	✅	✅	✅	✅	✅	✅	❌
Z3_solver_congruence_*	✅	✅	✅	✅	✅	✅	✅	❌
Z3_solver_set_initial_value	✅	✅	✅	✅	✅	✅	✅	❌
Z3_solver_register_on_clause	✅	✅	✅	❌	❌	❌	❌	❌
Z3_solver_solve_for	✅	❌	✅	✅	✅	✅	✅	❌
Z3_solver_from_file	✅	✅	✅	✅	✅	✅	✅	❌

Optimize API Coverage Matrix

C API Function	Python	.NET	C++	Java	TypeScript	Go	OCaml	Rust
Z3_optimize_check	✅	✅	✅	✅	✅	✅	✅	✅
Z3_optimize_get_lower	✅	✅	✅	✅	❌	✅	✅	❌
Z3_optimize_get_upper	✅	✅	✅	✅	❌	✅	✅	❌
Z3_optimize_get_lower_as_vector	✅	✅	✅	✅	❌	✅	❌	❌
Z3_optimize_get_upper_as_vector	✅	✅	✅	✅	❌	✅	❌	❌
Z3_optimize_get_unsat_core	✅	✅	✅	✅	❌	✅	✅	✅
Z3_optimize_get_objectives	✅	✅	✅	✅	❌	✅	✅	✅
Z3_optimize_get_reason_unknown	✅	✅	✅	✅	❌	✅	✅	✅
Z3_optimize_from_file	✅	✅	✅	✅	❌	✅	✅	❌
Z3_optimize_translate	✅	❌	✅	❌	❌	❌	❌	❌
Z3_optimize_register_model_eh	✅	❌	✅	❌	❌	❌	❌	❌
Z3_optimize_set_initial_value	✅	✅	✅	✅	✅	❌	❌	❌

---

Notes on Analysis Method

• C API baseline: src/api/z3_api.h and src/api/z3_optimization.h
• Language binding files checked:
  • Python: src/api/python/z3/z3.py
  • .NET: src/api/dotnet/Solver.cs, src/api/dotnet/Optimize.cs, src/api/dotnet/OnClause.cs
  • C++: src/api/c++/z3++.h
  • Java: src/api/java/Solver.java, src/api/java/Optimize.java
  • TypeScript: src/api/js/src/high-level/types.ts, src/api/js/src/high-level/high-level.ts
  • Go: src/api/go/solver.go, src/api/go/optimize.go
  • OCaml: src/api/ml/z3.ml, src/api/ml/z3.mli
  • Rust: https://github.com/prove-rs/z3.rs (cloned at commit HEAD)

AI generated by API Coherence Checker

• expires on Mar 3, 2026, 4:54 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-03T16:54:39.535Z.

Closed by Workflow