Java/Rust Parity & Generator

TeaQL uses one domain model to generate multiple implementation targets. The Java and Rust stacks share the same core idea: generated domain APIs, readable query builders, relation loading, runtime context, checkers, events, graph writes, and safe value access.

Parity does not mean every framework feature is copied across stacks. Spring Boot autoconfiguration, Java GraphQL integration, and Java web/service conventions are Java-specific unless a Rust-native target is explicitly designed. Rust adapts the shared model to crates, explicit runtime modules, provider-backed repositories, and async execution.

One Model, Two Generated Targets

teaql-code-gen supports both Java and Rust generation paths from the same TeaQL model.

Scope	Java target	Rust target
Library package	java-lib	rust-lib
Coding-agent guide	java-agent	rust-agent
Project manifest	Gradle / Maven	Cargo.toml
Entity type	Java POJO entity	#[derive(TeaqlEntity)] struct
Query facade	Java Q class	Rust Q facade
Safe expression mechanism	Java E AST expressions	Rust E expressions & EvalResult
Runtime context	Java UserContext	Rust teaql_runtime::UserContext
List result	Java SmartList<Entity>	Rust SmartList<T>
Repository model	Java repositories / Spring integration	provider-backed Repository API
Runtime registration	framework wiring	RuntimeModule, module(), registries

Query API Mapping

The Rust generator aligns with Java TeaQL's readable generated query style.

Java:

Q.merchants().selectName()
    .withNameContains("TeaQL")
    .top(20)
    .comment("Query merchants").purpose("Load data")
    .executeForList(userContext);

Rust:

Q::merchants().select_name()
    .with_names_contain("TeaQL")
    .top(20)
    .comment("Query merchants").purpose("Load data")
    .execute_for_list(&ctx)
    .await?;

The current Rust query generator covers the main Java-style query surface:

• default Q::entities() entrypoints
• minimal and children entrypoint shapes
• scalar field projection and unprojection
• select_self(), select_all(), select_any()
• relation loading through select_relation() and select_relation_with(...)
• readable filters such as with_names_contain(...)
• generic FieldOperator
• direct Expr composition for escape hatches
• relation subquery filters
• have_*() and have_no_*() helpers
• sorting, paging, top, offset, page, and unlimited
• grouped aggregation and generated aggregate helpers
• relation aggregate helpers such as count/statistics from child lists
• list, first, one, page, id, count, exists, records, and record execution helpers

Agent Tool Sandbox Mapping

Both stacks implement a unified Capability Sandbox for AI agents, guaranteeing strict intent auditing and opt-in capabilities. This ensures both stacks look practically identical to an AI Agent while leveraging their language's strongest security mechanics under the hood.

Java (JPMS SPI & Interface Downcasting):

ctx.http().post(url, body)
    .auditAs("Sync inventory data")
    .execute();

Rust (Cargo Features & Typestate):

ctx.http().post(url, body)
    .audit_as("Sync inventory data")
    .execute()
    .await?;

Runtime Mapping

Java TeaQL centers runtime behavior around UserContext. Rust keeps that architectural idea but adapts it to Rust runtime composition.

Java concept	Rust equivalent
UserContext execution boundary	teaql_runtime::UserContext
metadata lookup	RuntimeModule and entity descriptors
repository resolution	repository registry and provider registration
checker infrastructure	Checker, CheckerRegistry, typed checker wrappers
translated validation messages	Language, built-in translators, language switching
entity mutation events	EntityEvent, EntityEventSink
graph save	GraphNode, entity.audit_as("Save operation").save(&ctx)
SQL debug logs	SQL logging options on UserContext
runtime customization hooks	RequestPolicy and repository behavior hooks

Generated Rust crates can expose:

my_domain::module()
my_domain::module_with_behaviors()
my_domain::module_with_checkers()
my_domain::module_with_behaviors_and_checkers()
my_domain::repository_registry()
my_domain::behavior_registry()
my_domain::checker_registry()

Java Features Carried Over

Rust already carries over these Java-style TeaQL ideas:

• generated business query APIs instead of handwritten SQL
• default live-row query semantics
• relation loading and nested relation enhancement
• relation aggregate enhancement
• graph writes with create/update/reference/remove state
• optimistic locking through id + version
• platform-level request policy through RequestPolicy
• checker registration and translated validation errors
• mutation event dispatch
• native Rust safe value access through zero-cost E expressions and EvalResult
• SmartList<T> result metadata
• server-driven payload helpers such as web style/action/response data
• simplified XLS block model as a framework-neutral structure

Important Differences

Some differences are intentional:

• Rust focuses on generated domain APIs and provider-backed repositories, not Spring Boot.
• Rust uses explicit crates and RuntimeModule registration instead of Java framework autoconfiguration.
• Rust provider support is focused on PostgreSQL, MySQL, SQLite, Meilisearch experiments, and MemoryRepository rather than the full Java database matrix.
• Java GraphQL and Java BaseService/web-controller generation are not Rust parity goals yet.
• Rust generated crates should be treated as disposable generated output; change the model and regenerate instead of editing generated files directly.

Generator Status

The Rust generator currently supports:

• Cargo.toml
• src/lib.rs
• generated entity structs
• relation attributes
• SmartList<crate::T> reverse relations
• runtime module registration
• repository and behavior registries
• generated request builders
• Q::entities() facade methods
• behavior skeletons
• checker skeletons
• Rust coding-agent guide files
• compile checks against local teaql-rs

Still evolving:

• typed checker generation depth
• Rust GraphQL target
• Rust service/web target
• Rust constants/enums for constant objects
• Rust autocomplete/tooling
• complete Java-style inheritance child enhancement runtime behavior

Coding Agent Rule

Generated Rust crates include agent guidance with one core rule:

Always prefer TeaQL-generated APIs over handwritten data-access code.

That means application code should use generated Q, E expressions, graph save helpers, module registration, and provider setup instead of hand-writing SQL, relation loading loops, DTO mapping, or repository orchestration.