Skip to main content

Six Languages, One Query Meaning: Closing TeaQL API Parity Gaps

· 2 min read
TeaQL Team
TeaQL Team
Core Team

“Supports six languages” should mean more than producing six directories that compile. The same model must preserve the same query meaning, loaded-state behavior and governance boundaries in every generated API.

TeaQL recently used Java's generated Request API as the semantic reference and ran paired generation tests across Rust, Go, Python, .NET and TypeScript. The work exposed gaps that ordinary runtime unit tests had missed.

The parity contract​

The final generator enforces these shared invariants:

  • plural names come from centralized naming metadata;
  • human classification comes only from explicit model metadata;
  • human predicates use whose and whoAre; non-human predicates use with and whichAre;
  • execution receives only UserContext and becomes available after purpose;
  • expression facades distinguish loaded null from not loaded;
  • known-wrong generated names are corrected, not retained as aliases.

Expressions revealed deeper differences​

Python lacked its generated E expression facade. Go needed both an E facade and loaded-state support. Without that state, a null database value and a field that was never selected can collapse into the same representation.

The generated expression tests now cover scalar values, relation IDs, null, not-loaded, fallback, list size and list traversal. This matters for dynamic projections and partial entity loading, where an absent column must not masquerade as a business null.

Compile the generated result​

Template assertions are useful but insufficient. The parity suite generates paired human and non-human models, inspects the actual public API, then compiles fresh workspaces against the current formal runtimes.

The final matrix passed Java gold-standard generation, six-language predicate parity, pluralization regression, TypeScript/Python/Rust/.NET generated compile-and-run checks, and Go generated compilation plus SQLite persistence and expression checks.

Cross-language consistency is not achieved by making every language look syntactically identical. It comes from centralizing semantic decisions and verifying each language's real generated surface.