[API Coherence] Solver and Model API Analysis - Feb 20, 2026

[github-actions[bot]]

Summary

This is the first systematic API coherence analysis for Z3's multi-language bindings. I analyzed 3 API families covering solver core functionality, diagnostic features, and model inspection across 7 programming languages: Java, .NET (C#), C++, Python, TypeScript/JavaScript, OCaml, and Go.

Statistics

• API Families Analyzed: 3 out of ~25 (12%)
• Languages Covered: 7
• Total Functions Checked: 15+ functions across all languages
• Inconsistencies Found: 2

Progress Tracking

This is run #1 of an incremental analysis. Future runs will cover:

• BitVector operations (sign_ext, zero_ext, rotate, extract, overflow checks)
• Array theory APIs
• Floating-point APIs
• Quantifier APIs (forall, exists, lambda)
• Tactic and Goal APIs

---

API Families Analyzed

1. Solver Core APIs

C API Functions: Z3_solver_push, Z3_solver_pop, Z3_solver_reset, Z3_solver_assert, Z3_solver_check, Z3_solver_check_assumptions, Z3_solver_get_model, Z3_solver_get_proof, Z3_solver_get_unsat_core

Status: ✅ All languages have complete coverage

All languages provide these essential solver operations:

• Python: push(), pop(), reset(), add(), check(), model(), proof(), unsat_core()
• Java: push(), pop(), reset(), add(), check(), getModel(), getProof(), getUnsatCore()
• C++: push(), pop(), reset(), add(), check(), get_model(), proof(), unsat_core()
• C#: Push(), Pop(), Reset(), Add(), Check(), Model, Proof, UnsatCore
• TypeScript: push(), pop(), reset(), add(), check(), model(), unsatCore()
• OCaml: push, pop, reset, add, check, get_model, get_proof, get_unsat_core
• Go: Push(), Pop(), Reset(), Assert(), Check(), Model(), Proof(), UnsatCore()

2. Solver Diagnostic APIs

C API Functions: Z3_solver_assert_and_track, Z3_solver_from_file, Z3_solver_from_string, Z3_solver_get_reason_unknown, Z3_solver_get_num_scopes, Z3_solver_get_statistics

Status: ⚠️ TypeScript missing assertAndTrack

Coverage by language:

• Python: ✅ Complete (assert_and_track, from_file, from_string, reason_unknown, statistics)
• Java: ✅ Complete (assertAndTrack, fromFile, fromString, getReasonUnknown)
• C++: ✅ Complete (overloaded add(e, p) for tracking, from_file, from_string, reason_unknown)
• C#: ✅ Complete (AssertAndTrack, FromFile, FromString, ReasonUnknown)
• TypeScript: ❌ MISSING assertAndTrack (has fromFile, fromString, reasonUnknown, numScopes)
• OCaml: ✅ Complete (assert_and_track, from_file, from_string, get_reason_unknown, get_num_scopes)
• Go: ✅ Complete (AssertAndTrack, FromFile, FromString, ReasonUnknown, NumScopes)

3. Model APIs

C API Functions: Z3_model_eval, Z3_model_get_num_consts, Z3_model_get_num_funcs, Z3_model_get_const_decl, Z3_model_get_func_decl

Status: ✅ All languages have coverage

All languages provide model evaluation and iteration:

• Python: eval(), iteration via __getitem__, __len__, decls()
• Java: evaluate(), getNumConsts(), getNumFuncs(), getConstDecl(), getFuncDecl()
• C++: eval(), iteration support
• C#: Evaluate(), NumConsts, NumFuncs, ConstDecls, FuncDecls
• TypeScript: eval(), iteration via entries(), length()
• OCaml: eval, iteration via get_num_consts, get_num_funcs, get_const_decl, get_func_decl
• Go: Eval(), NumConsts(), NumFuncs(), ConstDecl(), FuncDecl()

---

High Priority Issues

Issue #1: Missing Solver.assertAndTrack in TypeScript

What: The Z3_solver_assert_and_track C API is not exposed in TypeScript/JavaScript bindings.

C API:

void Z3_API Z3_solver_assert_and_track(Z3_context c, Z3_solver s, Z3_ast a, Z3_ast p);

Available in: C, C++, Python, .NET, Java, OCaml, Go
Missing in: TypeScript/JavaScript

Purpose: This API is essential for extracting minimal unsat cores. It associates a constraint with a tracking literal (Boolean constant) that can later be retrieved via unsatCore() to identify which constraints caused unsatisfiability.

Use Case:

// Desired usage (currently not possible):
const solver = new Solver(ctx);
const p1 = Bool.const('p1');
const p2 = Bool.const('p2');

solver.assertAndTrack(x.gt(0), p1);  // ❌ Method does not exist
solver.assertAndTrack(x.lt(0), p2);  // ❌ Method does not exist

if (await solver.check() === 'unsat') {
  const core = solver.unsatCore(); // Would contain p1 and p2
}

Current Workaround: Users must use check() with assumptions, which is less flexible.

Fix Recommendation: Add assertAndTrack(constraint: Bool, track: Bool): void method to the Solver class in TypeScript.

Files to Modify:

• src/api/js/src/high-level/types.ts - Add method signature to Solver interface
• src/api/js/src/high-level/high-level.ts - Implement the method calling Z3.solver_assert_and_track

Priority: HIGH - This is a core diagnostic feature used for debugging unsatisfiable formulas.

---

Issue #2: Missing Optimize.assertAndTrack in TypeScript

What: The Z3_optimize_assert_and_track C API is not exposed in TypeScript/JavaScript bindings.

C API:

void Z3_API Z3_optimize_assert_and_track(Z3_context c, Z3_optimize o, Z3_ast a, Z3_ast t);

Available in: C, C++, Python, .NET, Java, OCaml, Go
Missing in: TypeScript/JavaScript

Purpose: Same as Issue #1 but for the Optimize solver, allowing tracking of constraints for unsat core extraction in optimization problems.

Fix Recommendation: Add assertAndTrack(constraint: Bool, track: Bool): void method to the Optimize class in TypeScript.

Files to Modify:

• src/api/js/src/high-level/types.ts - Add method signature to Optimize interface
• src/api/js/src/high-level/high-level.ts - Implement the method calling Z3.optimize_assert_and_track

Priority: HIGH - Essential for debugging optimization problems.

---

Observations

Excellent Coverage Overall

Z3's language bindings show remarkable consistency. The core solver APIs are 100% covered across all 7 languages, which is outstanding for a project of this complexity.

TypeScript Gaps

TypeScript bindings are newer and still catching up to the maturity of other bindings. The missing assertAndTrack methods are the only significant gaps found in this analysis round.

Naming Conventions

Each language follows its native conventions appropriately:

• Java/C#: PascalCase/camelCase (e.g., assertAndTrack, AssertAndTrack)
• Python/OCaml: snake_case (e.g., assert_and_track)
• TypeScript: camelCase (e.g., fromFile, numScopes)
• Go: PascalCase for exported methods (e.g., AssertAndTrack)
• C++: snake_case (e.g., get_model, overloaded add)

This is good practice and makes each binding feel native to its ecosystem.

---

Next Analysis (Run #2)

The next analysis will focus on:

1. BitVector Operations: Check coverage of sign_ext, zero_ext, rotate_left, rotate_right, extract, and overflow checking functions
2. Array Theory APIs: Verify select, store, and array property functions
3. Floating-Point APIs: Check FPA rounding mode and arithmetic operations

---

Methodology

This analysis was conducted using:

• Direct inspection of C API headers (src/api/z3_api.h, src/api/z3_optimization.h)
• Systematic grep searches across all language binding directories
• Verification of specific API presence in each language
• Cross-referencing with examples and test files

All findings were verified against the current codebase state as of February 20, 2026.

---

Maintainer Action Items

1. ✅ Quick Win: Implement assertAndTrack for TypeScript Solver and Optimize classes (estimated 2-4 hours)
2. ⏭️ Continue monitoring for new gaps as APIs evolve
3. 📊 Consider this ongoing coherence analysis for future API additions

AI generated by API Coherence Checker

• expires on Feb 27, 2026, 4:17 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-27T04:17:40.584Z.

Closed by Workflow