By introducing the new java-web-quarkus and java-web-micronaut generation targets, TeaQL ensures you can leverage the exact same deterministic models and generated data-access logic across the most popular cloud-native Java frameworks today.

Beyond Spring Boot​

While Spring Boot remains a powerhouse in the enterprise ecosystem, the demand for lightweight, fast-starting, and memory-efficient frameworks like Quarkus and Micronaut has grown rapidly—especially in serverless and container-heavy environments.

Our goal with TeaQL is to be framework-agnostic at the domain level. By separating our core execution logic into teaql-provider-jdbc, we were able to seamlessly integrate our triple-intent runtime into the CDI-based dependency injection systems of Quarkus and Micronaut.

Architecture & Dependencies​

To make this multi-framework support possible, we designed a clean separation between the domain logic and the framework-specific infrastructure. Depending on the framework you choose, your generated project will rely on a specific set of TeaQL components:

Spring Boot Architecture​

When targeting java-web-spring-boot, the architecture natively embraces Spring's ecosystem:

• teaql-provider-spring-jdbc: The core execution adapter that binds TeaQL's AST to Spring's NamedParameterJdbcTemplate.
• teaql-data-service-sql: The standard SQL generation and metadata service.
• Infrastructure: Standard Spring Boot starters for Web and JDBC, utilizing Spring's @Configuration and @Bean lifecycle.

Quarkus Architecture​

For java-web-quarkus, we bypassed Spring dependencies entirely to keep the runtime lightweight and native-friendly:

• teaql-provider-jdbc: A pure JDBC provider that connects directly to any javax.sql.DataSource.
• teaql-data-service-sql: The shared SQL runtime engine.
• Infrastructure: The generated application utilizes quarkus-resteasy-reactive-jackson for web endpoints, quarkus-agroal for high-performance connection pooling, and standard @ApplicationScoped CDI beans for registering the TeaQL runtime.

Micronaut Architecture​

Similarly, for java-web-micronaut, we optimized for Micronaut's ahead-of-time (AOT) compilation:

• teaql-provider-jdbc: The same pure JDBC provider used in Quarkus.
• teaql-data-service-sql: The shared SQL runtime engine.
• Infrastructure: The output project uses micronaut-http-server-netty and @Singleton bean configurations, wiring natively into Micronaut's HikariCP data sources.

Both new targets share the same underlying Java 21 java-lib-core library. Your business logic, data models, entities, and generated expressions remain 100% identical and portable.

Try It Out​

Generating a new Quarkus or Micronaut project is as simple as changing the scope parameter when invoking the generator:

# For Quarkus
mvn exec:java -Dexec.mainClass="com.skynet.codegenerator.LocalGenerator" \
  -Dexec.args="java-web-quarkus /path/to/output model.xml"

# For Micronaut
mvn exec:java -Dexec.mainClass="com.skynet.codegenerator.LocalGenerator" \
  -Dexec.args="java-web-micronaut /path/to/output model.xml"

We believe that your domain logic should outlive any specific framework. With these additions, TeaQL continues to deliver on the promise of durable, portable, and bug-free business code.

This update ensures that any project generated with the java-web-spring-boot target will out-of-the-box leverage the modern Spring ecosystem, providing an even more robust and observable runtime for your business APIs.

Embracing Java 21​

With this release, TeaQL leaves Java 17 behind and fully embraces Java 21 as the baseline for both java-lib-core and the generated Spring Boot projects. This alignment allows your generated code and custom extensions to seamlessly utilize modern Java features like Virtual Threads (Project Loom), Pattern Matching, and Record patterns.

What's New with Spring Boot 4.1 Integration​

Spring Boot 4.1.0 brings a host of powerful new features, and the TeaQL runtime has been validated to work perfectly alongside them:

Native gRPC Support​

Spring Boot 4.1 introduces native gRPC auto-configuration for both client and server applications. If you are extending your TeaQL-generated application with gRPC services, you can now use @GrpcAdvice for centralized exception handling and unified observation conventions without relying on third-party starter dependencies.

Enhanced Security with SSRF Mitigation​

The new HTTP client Server-Side Request Forgery (SSRF) mitigation via InetAddressFilter is now available to your TeaQL applications. This provides an additional layer of security by allowing strict whitelisting and blacklisting of address ranges for outbound requests.

Advanced Observability​

The updated OpenTelemetry support in Spring Boot 4.1 seamlessly integrates with TeaQL's generated API boundaries. Your generated queries, aggregations, and graph mutation operations can now be monitored with even greater precision.

Try It Out​

You don't need to learn a new DSL or update your domain models to take advantage of this upgrade. Simply regenerate your project using the java-web-spring-boot target, and your new project structure and pom.xml will be automatically provisioned with Spring Boot 4.1.0 and Java 21.

Here is what your generated POM properties will look like:

<properties>
    <java.version>21</java.version>
    <spring-boot.version>4.1.0</spring-boot.version>
    <!-- ... -->
</properties>

We remain committed to keeping TeaQL's output aligned with the industry's best practices and latest stable frameworks. Happy generating!

The results successfully demonstrated the power of declarative data models.

The Setup​

We used a single vending.xml model definition, which describes a complete vending machine domain (machines, products, inventory, transactions, and orders).

We then generated three separate web applications pointing to the exact same PostgreSQL database:

1. 005-vending-machine-web-spring-boot (Spring Boot 4.1.0)
2. 006-vending-machine-web-quarkus (Quarkus 3.8.3)
3. 007-vending-machine-web-micronaut (Micronaut 4.3.8)

A Shared Core​

At the heart of the test was the java-lib-core module. Regardless of the target web framework, the core library—containing the entities, expressions, checkers, and UserContext definitions—was generated identically.

Because TeaQL encapsulates all relational and structural logic inside the generated SmartList, SearchRequest, and Expression APIs, the upper layer web applications required zero manual translation.

Framework Adaptation​

The true test was adapting TeaQL's execution engine to the distinct lifecycle and dependency injection models of each framework:

• In Spring Boot, the runtime leveraged SpringJdbcSqlExecutor with NamedParameterJdbcTemplate.
• In Quarkus, the runtime successfully utilized the framework-neutral teaql-provider-jdbc adapter, binding natively to AgroalDataSource via CDI @Produces.
• In Micronaut, the application wired the same JDBC adapter using @Singleton definitions and native HikariCP data sources.

Conclusion​

All three applications compiled successfully under Java 21, connected to PostgreSQL, and managed to execute complex object-graph saves and reads without any hallucinations or manual SQL intervention.

This multi-framework capability ensures that teams adopting TeaQL are never locked into a single ecosystem. Whether you are building monolithic applications in Spring Boot or deploying lightning-fast native binaries with Quarkus, your data access layer remains pristine, consistent, and strictly aligned with your business intentions.

1. JPMS module boundaries — seal internal packages, expose only what generated code needs
2. Spring Boot independence — run without Spring Boot using a plain main() function
3. Rust alignment — dual-layer audit logging, compile-time query enforcement, RequestPolicy

Why Refactor?​

The Java runtime had grown organically. All classes lived in flat packages — any code could access RepositoryAdaptor, GLobalResolver, GraphMutationEngine, and other internals. The Rust version had already solved this with proper module boundaries and ownership-based safety. We wanted the same discipline in Java.

Architecture: Three Layers​

┌──────────────────────────────────────────────────┐
│ Layer 1: Application                             │
│   Spring Boot App / Plain Java App / Android App │
│   ↕ limited interfaces                           │
├──────────────────────────────────────────────────┤
│ Layer 2: Generated Code (teaql-code-gen output)  │
│   Entity, Request(Q), Checker, BaseService       │
│   ↕ limited interfaces                           │
├──────────────────────────────────────────────────┤
│ Layer 3: Runtime (teaql modules)                 │
│   public API + sealed internal implementation     │
└──────────────────────────────────────────────────┘

JPMS Module Boundaries​

We added module-info.java across the Java runtime modules. The core teaql module exports only what generated code needs:

module io.teaql {
    // === Public API (generated code uses these) ===
    exports io.teaql.data;
    exports io.teaql.data.checker;
    exports io.teaql.data.criteria;
    exports io.teaql.data.meta;
    exports io.teaql.data.translation;
    exports io.teaql.data.web;
    exports io.teaql.data.value;
    exports io.teaql.data.lock;
    exports io.teaql.data.log;

    // === Sealed internals (precise authorization) ===
    exports io.teaql.data.repository to io.teaql.sql, io.teaql.memory, io.teaql.sql.portable;
    exports io.teaql.data.internal to io.teaql.autoconfigure, io.teaql.sql;
}

Internal packages stay outside the normal application API surface:

• graph — mutation engine
• event — event classes
• xls — Excel export
• idgenerator — ID generation
• parser — expression parsers
• internal — RepositoryAdaptor, GLobalResolver, TempRequest

Translator implementations under language are public runtime types, with narrow reflective access where framework integration needs it.

We moved 5 classes from io.teaql.data to io.teaql.data.internal:

• RepositoryAdaptor — graph save orchestrator
• GLobalResolver — static resolver holder
• TempRequest — temporary query wrapper
• RequestAggregationCacheKey — cache key
• SimpleChineseViewTranslator — internal translator

Spring Boot Independence​

We created a TQLResolver interface that replaces Spring's ApplicationContext:

public interface TQLResolver {
    <T> T getBean(Class<T> clazz);
    <T> List<T> getBeans(Class<T> clazz);
    <T> T getBean(String name);
    Repository resolveRepository(String type);
    EntityDescriptor resolveEntityDescriptor(String type);
}

For non-Spring environments, a simple Map-based implementation works:

static class SimpleResolver implements TQLResolver {
    private final Map<Class<?>, Object> beans = new HashMap<>();
    private final Map<String, Repository<?>> repos = new HashMap<>();

    @Override public <T> T getBean(Class<T> clazz) {
        return clazz.cast(beans.get(clazz));
    }
    @Override public Repository resolveRepository(String type) {
        return repos.get(type);
    }
}

A robot-kanban demo app runs with a plain main():

public static void main(String[] args) {
    DataSource dataSource = createDataSource(); // SQLite
    EntityMetaFactory metaFactory = new SimpleEntityMetaFactory();
    // ... register metadata, repositories, checkers

    TQLResolver resolver = new SimpleResolver(metaFactory, repos, checkers, config);
    GLobalResolver.registerResolver(resolver);

    UserContext ctx = new UserContext();
    ctx.setRequestPolicy(new PurposeRequestPolicy());
    ctx.setLogManager(new LogManager());

    // Use Q/E API
    Q.taskStatuses()
        .comment("查询任务状态")
        .purpose("展示看板")
        .executeForList(ctx);
}

Compile-Time Query Enforcement​

In Rust, you literally cannot call execute_for_list without setting comment — the type system prevents it. In Java, we achieve similar约束 with ExecutableRequest:

// purpose() is the terminal method — returns ExecutableRequest
Q.tasks()
    .filterByName("xxx")
    .comment("查询任务")
    .purpose("展示看板")     // → ExecutableRequest
    .executeForList(ctx);    // only ExecutableRequest has this

// Without purpose(): no ExecutableRequest, no executeForList
Q.tasks().executeForList(ctx);  // compile error

The purpose() method validates that comment is set:

public ExecutableRequest<T> purpose(String purpose) {
    if (comment == null || comment.isEmpty()) {
        throw new RepositoryException(
            "[PURPOSE FAILED] Missing .comment() on " + getTypeName());
    }
    this.purpose = purpose;
    return new ExecutableRequest<>(this);
}

RequestPolicy (Rust Alignment)​

We ported Rust's RequestPolicy trait to Java:

public interface RequestPolicy {
    default void enforceSelect(UserContext ctx, SearchRequest<?> query) {}
    default void enforceInsert(UserContext ctx, Entity entity) {}
    default void enforceUpdate(UserContext ctx, Entity entity) {}
    default void enforceDelete(UserContext ctx, Entity entity) {}
    default void enforceRecover(UserContext ctx, Entity entity) {}
}

PurposeRequestPolicy enforces both query purpose and audit comments:

ctx.setRequestPolicy(new PurposeRequestPolicy());

// Rejects: no purpose
Q.taskStatuses().comment("x").executeForList(ctx);
// → [PURPOSE REQUIRED] Query on TaskStatus rejected.

// Rejects: no auditAs
entity.save(ctx);
// → [AUDIT REQUIRED] insert on Task rejected.

Dual-Layer Audit & Logging​

The Rust design has two layers: a raw file log controlled by environment variables, and customizable app-level sinks with masked data. We ported this exactly.

Layer 1: Runtime (Environment Variables, No Code)​

TEAQL_LOG_ENDPOINT=/var/log/teaql.log  # file path
TEAQL_LOG_FORMAT=human                 # human | json
TEAQL_LOG_SELECT=true                  # log SELECT queries
TEAQL_LOG_MUTATION=true                # log mutations

Writes raw, unmasked SQL and audit information. No code customization.

Layer 2: App Layer (Customizable, Masked)​

LogManager logManager = new LogManager();

// Audit sink: receives masked events
logManager.addAuditSink((ctx, event) -> {
    saveToDatabase(event);
    sendToMessageQueue(event);
});

// Log sink: receives masked SQL logs
logManager.addLogSink(entry -> {
    showOnUI(entry);
});

ctx.setLogManager(logManager);

Masking (Aligned with Rust)​

The masking algorithm matches Rust's mask_audit_value and limit_audit_value:

// Field-level masking (from EntityDescriptor._audit_mask_fields)
maskAuditValue("12345678") → "12****78"
maskAuditValue("1234")     → "****"

// Length truncation (from EntityDescriptor._audit_value_max_len)
limitAuditValue("very long string...", 200) → "head...tail"

Configuration comes from the entity model:

<task_execution_log
    _audit_mask_fields="detail"
    _audit_value_max_len="2048"
/>

Multi-Framework Support via TeaQLDatabase​

We introduced TeaQLDatabase as the universal database abstraction layer. Portable runtimes share the same SQL repository shape (PortableSQLRepository), only the database driver differs:

Entity → PortableSQLRepository → TeaQLDatabase → Database
              ↑                    ↑
        Reuses SQL building    Abstraction layer
        (ExpressionHelper)     Android: SQLiteDatabase
                               Quarkus: AgroalDataSource
                               Micronaut: DataSource
                               JVM test: JDBC

Android​

TeaQLDatabase db = new AndroidDatabase(sqLiteDatabase);

Quarkus (CDI integration)​

<dependency>
    <groupId>io.teaql</groupId>
    <artifactId>teaql-quarkus</artifactId>
</dependency>

@Inject
TeaQLDatabase db;

The TeaQLProducer provides default beans via CDI @Produces. Application can override any bean.

Micronaut (Bean Factory integration)​

<dependency>
    <groupId>io.teaql</groupId>
    <artifactId>teaql-micronaut</artifactId>
</dependency>

@Inject
TeaQLDatabase db;

The TeaQLFactory provides default beans via @Factory + @Bean. Application can override any bean.

Plain Java (no framework)​

TeaQLDatabase db = new QuarkusDatabase(dataSource); // or any JDBC DataSource
EntityMetaFactory metaFactory = new SimpleEntityMetaFactory();
// ... register metadata, repositories, checkers

TQLResolver resolver = new SimpleResolver(metaFactory, repos, checkers, config);
GLobalResolver.registerResolver(resolver);

Key change: ExpressionHelper.toSql() now accepts SQLColumnResolver instead of SQLRepository, so PortableSQLRepository can reuse the expression parsing logic without depending on spring-jdbc.

Summary Table​

The Java runtime is now modular, Spring Boot optional, multi-framework ready (Spring Boot / Quarkus / Micronaut / Android / Plain Java), and aligned with the Rust architecture on all critical design points.

Business software has a different risk profile from a small demo. It carries business rules, audit requirements, data boundaries, operational workflows, and long-lived maintenance obligations. If an AI coding agent works in that environment, the important question is not only whether it can produce code once. The important question is whether its work can be measured, reviewed, and traced back to evidence.

That is why this report exists.

What This Report Is​

Report 001 is our first public autonomous evaluation report for TeaQL agent workflows. It looks at how an AI coding agent behaves when working against TeaQL's generated business API surface and evaluation materials.

The report is not presented as a universal industry benchmark. It is an early, public, reproducible evaluation artifact for TeaQL's own agent-facing approach. Its value is in the evidence it exposes:

• the tasks being evaluated
• the agent behavior observed during the run
• the measured outcomes
• the failure patterns
• the lessons for stronger guardrails and better agent workflows

That evidence matters more than a single success story.

Why Publish Reports​

AI coding tools can look convincing when the output is shown without context. For business software, that is not enough. Teams need to understand how the result was produced, where the agent stayed inside the intended API boundary, where it drifted, and what kinds of mistakes still require evaluation and review.

TeaQL is designed around that premise. Generated APIs, structured model information, audit-aware operations, and evaluation workflows should make agent work easier to inspect. Publishing evaluation reports is a way to apply the same discipline to TeaQL itself.

The PDF is the readable summary. The raw data is the evidence trail.

How To Read It​

Readers do not need to treat the report as marketing material. A better way to read it is as an engineering artifact:

1. Start with the task definitions.
2. Check what the agent actually produced.
3. Compare the result against the intended TeaQL API boundary.
4. Look at the evaluation notes and failure patterns.
5. Use the raw data to verify the summary instead of trusting the summary alone.

This is also how we want TeaQL adoption to work: not by hiding complexity, but by making the important parts reviewable.

What Comes Next​

Report 001 is only a first step. Future evaluations should cover more tasks, more agent tools, more models, and clearer comparisons across time. The goal is not to claim that autonomous coding is solved. The goal is to make progress visible, repeatable, and honest enough for serious software teams to reason about.

You can read the report here:

• Download TeaQL Evaluation Report 001
• View the raw evaluation data

However, while enjoying the ultimate performance of multi-destination storage, we often find ourselves trapped in a painful "code swamp."

1. The Pain Points: The "Schizophrenia" of Multiple Data Sources and AI Disasters​

If you implement such polyglot persistence using traditional architectures, your business code will typically be littered with scenarios like this:

// Traditional business logic Frankenstein
if entity.is_task() {
    pg_pool.execute("INSERT INTO task...", &task).await?;
} else if entity.is_execution_log() {
    meilisearch_client.index("task_execution_log").add_documents(&log).await?;
}

We have to configure multiple connection pools, introduce multiple ORMs or SDKs, and even write hundreds of lines of IF/ELSE blocks in the business logic just to keep the data synchronized.

In the era of AI-assisted programming (Agentic Coding), this architecture is extremely unfriendly to AI. If an AI Agent needs to navigate such a codebase, it must simultaneously master the API syntax of multiple underlying databases. With the slightest mistake, it will mix up Postgres syntax with the Meilisearch SDK, generating disastrous code hallucinations. Not to mention, when the architecture evolves and you want to migrate an entity from MySQL to Elasticsearch, the related business logic often faces the risk of being completely scrapped and rewritten.

We need an ultimate solution designed for Agents.

2. TeaQL's Solution: The "Underscore Philosophy" and "Inheritance Mechanism"​

In the TeaQL framework, we adhere strictly to the philosophy of "Model as the Single Source of Truth". How do we elegantly resolve routing across multiple data services? We compress all the complexity into the system core, leaving only a simple multiple-choice question for developers (or AI) in the XML model file.

Let's look at how a TeaQL model defines the destination of data storage:

<!-- 1. Global configuration: Define the overall data_service on the root node. The entire domain defaults to rusqlite. -->
<root name="robot-kanban-service" org="doublechaintech" data_service="rusqlite">

    <!-- 2. Default inheritance: No data service declared here; automatically inherits rusqlite from root to go to relational storage. -->
    <task 
        name="string()" 
        status="string()"
    />
  
    <!-- 3. Local override: Business requires logs to support full-text search, so we explicitly switch to meilisearch via _data_service. -->
    <task_execution_log
        action="string()"
        detail="string()"
        _data_service="meilisearch" 
    />

</root>

Why the "Underscore"?​

Hidden here is a core syntax design of the TeaQL parser: distinguishing business data fields from framework metadata.

• Attributes without an underscore (such as name="string()" or data_service on the root node) are treated by the parser as business-level entity data fields (Fields).
• Attributes prefixed with an underscore (such as _data_service or _audit_mask_fields) represent metadata (Metadata) that controls framework behavior.

If we wrote data_service="meilisearch" without the underscore on <task_execution_log>, the parser would assume that the task has a business field named data_service! Through this ultra-minimal underscore convention, we achieve complete decoupling of business and framework configuration without breaking the purity of the XML at all.

3. Architectural Magic: Transparent Dispatching Under the Hood​

When the generator scans the model above, it reads _data_service and passes the context to the STG templates. The final entity code generated on the Rust side looks like this:

#[derive(Clone, Debug, PartialEq, TeaqlEntity)]
// The macro is injected with data_service = "meilisearch"
#[teaql(entity = "TaskExecutionLog", table = "task_execution_log_data", data_service = "meilisearch")]
pub struct TaskExecutionLog { ... }

What magic does this bring to the business-layer code? No matter where the underlying tables actually reside, the business-layer developers and AI see only one interface: a unified, elegant TeaQL domain-specific language API.

// Business code: Saving a task automatically routes to rusqlite under the hood
let mut task = Task::new("Deploy App");
ctx.save(&task).await?;

// Business code: Saving a log automatically invokes the Meilisearch Provider SDK under the hood
let mut log = TaskExecutionLog::new("System start");
ctx.save(&log).await?;

No "glue code", no ugly conditional branches. Through the underlying Rust Trait mechanism (Providers), ctx.save() acts like a smart mail sorting station, accurately dispatching data to its proper place based on the data_service label attached to each entity's head.

4. The Pinnacle of Agentic Coding: Reducing Cognitive Load​

Under an architecture like TeaQL:

1. Preventing Human Error: Business developers will never write data to the wrong database due to mistakenly calling the wrong connection pool.
2. Unleashing AI Potential: When generating complex business logic flows, AI no longer needs to read the API manuals of various data components.

We have split "architectural decision-making" and "business coding" into their most logical stages. During the modeling phase, the AI or architect determines the physical layer direction with a single _data_service attribute; during the coding phase, no matter what business logic code is generated, the underlying layer maintains absolute consistency and security.

A truly excellent modern framework must not only serve humans but also understand how to elegantly guide AI collaboration. TeaQL is a pioneering work born exactly from this philosophy.

While business logic is becoming increasingly easy to generate automatically, the audit chain must not become fragile as a result.

Traditional audit systems often rely on business code to actively record logs. However, in AI Coding scenarios, this approach carries clear risks:

• AI might forget to write audit logs;
• AI might accidentally disable logs;
• AI might generate code that bypasses audits;
• Business code might unintentionally record sensitive plain text;
• A custom audit hook might access raw data it shouldn't see;
• Long strings, JSON payloads, or execution logs might cause audit log bloating or even out-of-memory (OOM) errors.

Therefore, TeaQL underwent a low-level refactoring to move auditing capabilities into the framework kernel rather than leaving them entirely to the business code. We established the following core principles:

Audit must be kernel-level.
Business code may enrich audit trails, but it cannot erase them.
Sensitive fields do not disappear; only their plain text disappears.

1. Kernel-Level Auditing to Prevent Mistakes Automatically​

Humans don't have the energy to make every possible mistake; our primary targets for defense are actually AI and automatically generated code. If an AI can write business logic, it is equally capable of mistakenly wiping out the audit chain or unintentionally logging sensitive plain text (such as passwords, tokens, etc.).

To guard against this, the TeaQL auditing system cannot be altered arbitrarily from the outside. In the TeaQL Rust Runtime, every data mutation (Insert/Update/Delete) is automatically triggered by the kernel.

Dual-Channel Design: Isolating Internal Auditing from Custom Hooks​

In previous versions, we provided a unified ctx.set_event_sink(), but this introduced conflicts. If a client overrode the sink to implement WebSocket push notifications, the infrastructure-level compliance audit logs would be lost.

To solve this, we strictly isolate internal system auditing from custom external user hooks:

1. Immutable Internal Auditing (Raw Event Sink): set_event_sink has been demoted to a pub(crate) internal behavior and is controlled solely by environment variables (e.g., TEAQL_AUDIT_ENABLED). AI-generated business code or client-side code can never modify or disable internal compliance auditing.
2. Secure External Customization (Custom Event Sink): We provide a clear public API: ctx.set_custom_event_sink(). This is the sole hook left open to the outside, allowing users to intercept log messages and perform further business processing (such as updating the UI in our robot kanban demo).

2. The Evolution from RawAuditEvent to SafeAuditEvent​

Isolating the sinks is not enough on its own. While internal compliance audits can write directly to databases or log collectors, events exposed to the external custom sink must be safe.

If we were to pass the complete raw event stream to a custom sink, it would mean client code or AI-generated logic could easily access raw sensitive data they shouldn't see, or crash the memory with bloated text.

To completely solve this, we split the event model into two layers:

1. RawAuditEvent: Contains 100% complete mutation data and raw requests, restricted for internal low-level use only.
2. SafeAuditEvent: A sanitized, masked, and truncated event model exposed to the outside.

Metadata-Based Automatic Masking and Truncation​

The core philosophy of TeaQL is: Model is the Single Source of Truth. By adding specific metadata attributes in the XML model, the code generator automatically generates Rust data structure descriptors (EntityDescriptor) containing safety policies.

In the latest model.xml, developers can define masking and truncation rules directly on the Entity:

<task_execution_log
    task="task()"
    action="string()"
    detail="string()"
    _audit_mask_fields="detail"
    _audit_value_max_len="2048"
    _data_service="meilisearch"
    _name="Task Execution Log"
/>

When a RawAuditEvent is passed to the CustomEventSink, the kernel-space UserContext retrieves the security descriptor for the corresponding entity via the MetadataStore and converts the RawAuditEvent into a SafeAuditEvent (a lock-free, highly efficient conversion process).

This conversion process automatically performs two core defenses:

1. Field-Level Masking: If a field is listed in _audit_mask_fields (such as passwords or sensitive content), TeaQL does not delete the field from the audit record. Instead, it replaces its value with *** MASKED ***. This preserves the principle that "sensitive fields do not disappear; only their plain text disappears," keeping the audit trail intact.

2. Automatic Long-Text Truncation: If a field contains a multi-megabyte JSON payload or error stack, sending it directly to an external hook could trigger an OOM error. TeaQL automatically truncates long strings in the safe event to a specified length based on _audit_value_max_len, appending ...(truncated).

3. Preventative Design in Modeling: A Fail-Fast Linter for AI​

Kernel-level interception at runtime is not enough. If an AI or developer forgets to add the _audit_mask_fields tag to highly sensitive fields like password or ssn during the modeling phase (when writing XML), plain text would still leak at runtime.

To address this, we have natively integrated a KSML Static Analysis and Evaluation Linter into the compile and code generation phase of TeaQL.

When a model is submitted to the framework, the PrivacyAuditEvaluationRule automatically performs lexical evaluations on all fields. Built specifically for Agentic Coding, this mechanism supports "fail-fast and self-healing":

1. Blocking Errors (Error): When core high-risk privacy fields (like password, token, or ssn) are detected without masking, the engine blocks code generation.
2. Actionable Fix Examples: The engine no longer throws cold stack traces; instead, it outputs clear snippets showing how to fix the issue. Whether a human is viewing the CLI or an AI is parsing a JSON response, they receive precise instructions:

   {
     "ruleId": "KSML-PRIVACY-001-ERR",
     "title": "High Sensitivity Data Unmasked",
     "message": "The field 'password' in entity 'user' contains highly sensitive keywords. You MUST mask it.\nFix Example: Update your XML entity definition:\n<user ... _audit_mask_fields=\"password\" />"
   }
   

3. Soft Warnings & Suggestions: For secondary sensitive fields like user_email or phone, the system does not block generation but packages warnings into .teaql/evaluation_report.json. The IDE plugin or an AI's subsequent task can read this report to display warning lines in the XML editor.

Conclusion​

With the rise of AI Coding, defensive design is no longer just about protecting against human typos—it's about keeping automated systems from running out of control in edge cases.

By (1) isolating the immutable compliance sink and (2) introducing the SafeAuditEvent automatically sanitized via model metadata, TeaQL builds an impassable barrier: no matter what business code the AI generates, it can never bypass audit baselines, nor can it accidentally leak sensitive data.

But this isn't a simple rollback. We've redesigned it from the ground up with zero-cost reference chaining and introduced a revolutionary structured panic mechanism that turns runtime errors into self-healing instructions for AI agents.

The Ping-Pong of API Design​

Early in our Rust port, we attempted to replicate Java's E:: expression wrappers. However, to satisfy the borrow checker without complex lifetime annotations, we ended up requiring .clone() on entire entity graphs. This was unacceptable in Rust.

Our first reaction was to swing the pendulum the other way. We introduced eval_xxx() methods and the EvalResult enum, forcing developers to use combinators like .and_then() to safely traverse graphs:

let result = user.eval_platform()
    .and_then("platform", |p| p.eval_company().and_then("company", |c| c.eval_name()));

While this was memory-safe and zero-cost, it destroyed the developer experience. As we often say: "Fluent expressions are mental candy for humans." Writing deeply nested closures just to read a nested property felt punishing.

Bringing Back E:: (The Right Way)​

We realized we could have our cake and eat it too. By carefully crafting lifetime-bound wrapper structs in the code generator, we brought back the E:: syntax without any of the .clone() overhead.

You can now write fluent chains in multiple ways depending on your error-handling preference:

// 1. Strict evaluation (Panics with structured AI diagnostic if missing)
let name = E::user(&user).get_platform().get_company().get_name().unwrap();

// 2. Safe Optional evaluation (Returns None if logically missing or naturally Null)
if let Some(name) = E::user(&user).get_platform().get_company().get_name().eval() {
    println!("Found name: {}", name);
}

// 3. Fluent fallback (Provides a default if missing or Null)
let name = E::user(&user)
    .get_platform()
    .get_company()
    .get_name()
    .or_else("Unknown Company".to_string());

Under the hood, all of these are zero-cost abstractions that simply pass references along the chain until the final terminator (unwrap, eval, or or_else) is called.

Strict Panics: Rust's Bottom Line​

But what happens if you try to traverse a relation that wasn't loaded from the database? In Java, you might get a silent null or a late NullPointerException. In our previous eval_xxx iteration, you got a safe EvalResult::NotLoaded enum.

With the return of E::, we decided to embrace a core Rust philosophy: Fail fast and fail loudly.

If you access an unloaded relation, the expression evaluates to a panic. But this is not your typical panic. It is a Structured Logic Bug Panic.

Designing for AI: The Structured Panic​

When building AI-native frameworks, errors shouldn't just halt execution; they should provide the exact recipe to fix the bug.

When an E:: expression encounters an unloaded relation, it triggers a highly structured diagnostic panic that looks like this:

================================================================================
☕ TeaQL Logic Bug Detected ☕
Severity: FATAL - System halted to prevent undefined business logic.

[Human Message]
You attempted to access a relation that was not loaded in the initial query.
Root Entity: User(id=42)
Attempted Path: platform.company.name

[Diagnostic Context]
original_expr_with_broken_point: E::user(id=42).get_platform().get_company()<broken>.get_name()
missing_preload: select_company()
suggested_fix: .select_platform_with(Q::platforms().select_company())

================================================================================

The Magic of <broken>​

The most crucial addition here is the original_expr_with_broken_point field. By injecting a visual <broken> marker exactly where the chain failed, we provide immense context.

When an AI agent (like our coding assistants) runs a test and hits this panic, it doesn't need to guess where the data is missing. It reads the structured payload, spots the <broken> marker, and immediately knows that the company relation needs to be loaded. It even gets the exact suggested_fix to append to its query builder.

Conclusion​

By combining zero-cost reference wrappers with highly structured, AI-readable panics, we've achieved the holy grail of framework design:

1. Human Ergonomics: Developers get the "mental candy" of fluent .get_foo().get_bar() chaining.
2. Performance: Zero allocations, purely reference-driven.
3. AI Auto-Healing: When things break, the framework hands the AI the exact instructions needed to rewrite its query and heal the code automatically.

In the AI era, an error is no longer a dead end—it's just a prompt for the next self-correction.

The addition of these two modules marks a significant milestone. TeaQL not only excels at the low-level data flow and auditing but also starts to provide out-of-the-box, exceptional experiences for developers and AI agents in top-level web request routing and distributed scaling.

1. The Web Module: Bridging the HTTP Layer and the Security Sandbox​

In traditional architectures, the web layer (controllers/routing) and the underlying business logic layer are often completely disconnected. Developers must manually extract tokens, trace IDs, and User-Agents from HTTP headers, then assemble and pass them down to the service layer.

teaql-web-integration-axum changes this completely. It seamlessly integrates the Rust community's outstanding Axum web framework with TeaQL's core security sandbox (UserContext).

Feature 1: TeaContext Extractor​

We implemented a native Axum extractor in the Web module. When a request hits your router, all critical metadata is automatically parsed from the HTTP message and encapsulated into a high-integrity, tamper-proof UserContext:

// Axum router handler
pub async fn load_tasks(ctx: TeaContext, payload: Json<TaskRequest>) -> impl IntoResponse {
    // Here, ctx has already parsed X-User-Id, X-Trace-Id, and the client's IP!
    // Directly proceed to core authorization and audit security base:
    let tasks = Q::tasks().execute_for_list(&ctx.0).await.unwrap();
    
    WebResponse::of_list(tasks)
}

Feature 2: Fully Compatible WebResponse​

During microservice evolution or frontend refactoring, API incompatibility is a major pain point. Our WebResponse struct has a built-in IntoResponse mapping mechanism for automatic status code resolution (including automatic intercepting of AxumTeaError). More importantly: its JSON serialization structure perfectly matches the previous Java Legacy API.

Whether it's a frontend application or an AI agent calling the endpoint via OpenAPI, no parser logic needs to be rewritten just because the backend transitioned to Rust.

Feature 3: Native Support for Facets (Aggregated Categorization)​

In modern e-commerce, dashboards, or complex business queries, we often need to return not just a list of items but also grouped metadata (such as status counts or temporal distributions) for rendering sidebars. In the search domain, this is referred to as Facets.

teaql-web-integration-axum provides first-class support for Facets. It accepts SmartList directly from the TeaQL Core engine (which comes with multi-dimensional facet data embedded) and formats it into the web response automatically:

// Get task list, with the engine calculating status-aggregated facets at the same time
let smart_list = Q::tasks().with_status_facets().execute_for_smart_list(&ctx).await?;

// Convert it into a standard Web API response containing both data and facets with one line of code
WebResponse::from_smart_list(smart_list)

Once the frontend receives the JSON, the data array is used to render the main list, and the facets dictionary is immediately ready to populate the sidebar filter options.

2. The Red Module: Distributed Cache with a Single Line of Code​

As concurrency increases, single-machine in-memory cache often reaches its limits. To address this, we launched the teaql-cache-integration-redis module.

The core philosophy of this module is: do not change any upper-level business code; simply replace the underlying provider to transition smoothly from single-machine to distributed caching.

It fully implements TeaQL's runtime DataStore trait. Developers and AI agents write the exact same, simple and unified syntax:

// Business code always uses this single syntax, independent of physical storage
ctx.put("daily_task_stats", stats_value, Some(3600)).await;
let stats = ctx.get("daily_task_stats").await;

At the initialization level, the architect only needs to inject the RedisDataStore:

let redis_store = RedisDataStore::new("redis://127.0.0.1:6379/0").await?;
let runtime = TeaRuntime::builder()
    .with_data_store(redis_store) // Instantly switch to distributed caching
    .build();

Summary: Moving Toward the Ultimate Agentic State​

The introduction of these two new modules is far more than just adding a couple of adapters. Their essence lies in reducing the external entropy of the system:

• The Web module collapses raw, messy HTTP protocols into a structured UserContext.
• The Red module abstracts complex Redis drivers into a unified DataStore interface.

When an AI agent writes business code on top of TeaQL, it only faces one clean pathway: grab the Context, access data, and return a Response. No protocol bickering, no switching between different SDKs.

TeaQL digests all the low-level heavy lifting inside the framework kernel, allowing the future of software development to truly focus on business value.

As an indispensable scaffolding and code generation engine in the entire TeaQL ecosystem, teaql-forge-rs carries the core mission of transforming human and AI high-level business intentions (.tql models) into production-ready executable code. Alongside the upgrade of the foundational teaql-rs and teaql-code-gen to v3.0, Forge has also welcomed its full open-source release.

What is teaql-forge-rs?​

In the past, building an enterprise-level application that complies with Domain-Driven Design (DDD) standards, includes built-in auditing, and supports complex relational queries often required writing a massive amount of boilerplate code.

teaql-forge-rs is a Rust-based code generation tool. By parsing the minimalist .tql DSL (Domain-Specific Language), it automatically generates your foundational domain models, type-safe Query APIs, database access layers (Repositories), and even scaffolding interfaces for frontend-backend interaction. Forge helps alleviate the repetitive labor when writing Rust services.

Core Features​

In this open-source release, teaql-forge-rs includes the following main features:

1. Lightweight Rust Generation Engine: A new, relatively streamlined Rust generation engine that supports automatic base code generation for CLI tools or Axum backend applications (Note: The closed-source commercial Java generation engine is not included here).
2. Triple-Intent Semantic API Generation: Fully supports the latest .comment(), .purpose(), and .audit_as() semantic chain call specifications. The code generated by Forge natively forces developers and AI to provide clear business intentions when operating on data, turning logs from unreadable text into business stories.
3. Lightning-Fast Parsing & DDL Mapping: Leveraging Rust's extreme performance, it can parse complex architectures with hundreds of entity definitions in an instant, and automatically map them to DDL structures across multiple databases (PostgreSQL, MySQL, SQLite).
4. Plug-and-Play DDD Structure: The generated code strictly adheres to Domain-Driven Design boundaries, perfectly decoupling the Q::entities() query interface from the persistence layer, drastically reducing maintenance costs and lowering the comprehension barrier for AI.

Docker Quick Start Guide​

To allow everyone to experience teaql-forge-rs with zero environment configuration, we provide an official Docker image. You just need to write a schema.tql, and let Docker handle the rest.

1. Prepare Your TQL Model File​

Create a schema.tql file in your current directory (for example, defining a simple task board):

entity Task {
    name: string
    status: string
}

2. One-Click Code Generation via Docker​

By starting a local Docker service container and using the local client tool, you can experience one-click generation:

1. Start the local code generation service:

docker run -d --name teaql-forge-server -p 8080:8080 teaql/teaql-forge-rs:latest

2. Seamlessly connect the client to the local service for generation:

Combined with the cargo-teaql client tool we provided previously, you simply point the generation endpoint to your local service using --endpoint-prefix to output the enterprise scaffolding and domain:

cargo-teaql gen-workspace --endpoint-prefix http://127.0.0.1:8080/ schema.tql --output ./generated-rust

Once it finishes running, you'll see the complete set of enterprise-grade Rust code in the generated-rust folder in your current directory! This is fully compatible with all operations in teaql-agent-kit.

Daily Development Guide After Generation​

After you generate code with teaql-forge-rs, your daily data operations will be completely oriented around domain objects, saying goodbye to tedious SQL string concatenation. Coupled with the latest "Triple-Intent" specification, the business intent of the code itself will be crystal clear.

1. Daily Data Queries and Filtering​

All query operations are unified through the Q::entities() entry point. You can use method chaining as naturally as speaking, and you are forced to attach clear business comments:

use generated_rust::Q;

let active_tasks = Q::tasks()
    .which_status_are("TODO")
    .page(1, 20)
    .comment("Retrieve board list data")
    .purpose("Display unfinished tasks")
    .execute_for_list(&ctx)
    .await?;

2. Business Workflows in DDD Mode​

In Domain-Driven Design (DDD), we recommend completing business logic on in-memory domain objects before uniformly persisting them. You can first query the object, modify its state, and finally save it using .audit_as() carrying the audit context:

// 1. Query the domain object
let mut task = Q::tasks()
    .with_id_is(42)
    .comment("Get task by ID")
    .purpose("Prepare to advance task workflow status")
    .execute_for_one(&ctx)
    .await?
    .expect("Task does not exist");

// 2. Pure in-memory state transition (via generated Setters or your own domain behaviors)
task.update_status_to("DONE")
    .update_name("Completed task");

// 3. Persist with human operational intent
task.audit_as("User clicked the [Mark as Done] button").save(&ctx).await?;

In this mode, the underlying interceptor will not only execute the corresponding SQL but also automatically generate an audit log with immense business value: [AUDIT] Task(42) UPDATED ... action: User clicked the [Mark as Done] button.

Automating Programming with AI Assistants​

A highly standardized, predictable underlying API surface is not only friendly to humans but also serves as "dessert" for large language models.

If you want AI to help you write business code with zero hallucinations, we strongly recommend using it in conjunction with teaql-agent-kit. This toolkit contains built-in Prompts and playgrounds for AI tools like Cursor and GitHub Copilot.

With it, you only need to describe your requirement to the AI:

"Find tasks where the name contains 'bug' and the status is 'TODO', and batch update their status to 'IN_PROGRESS'."

The AI will be able to effortlessly and 100% accurately output the following code:

let mut tasks = Q::tasks()
    .which_names_contain("bug")
    .which_status_are("TODO")
    .comment("Retrieve historical Bugs")
    .purpose("Batch advance Bug status")
    .execute_for_list(&ctx)
    .await?;

for mut task in tasks {
    task.update_status_to("IN_PROGRESS");
    task.audit_as("Automatically advance Bug processing progress").save(&ctx).await?;
}

Through unified semantic API specifications, your AI assistant will truly evolve into a senior engineer that never makes mistakes.

Conclusion​

In the era of Agentic Coding, we need a more predictable and semantic underlying API surface. The open-sourcing of teaql-forge-rs is a crucial step towards our vision of "Code is Business Intent".

Welcome to visit the GitHub repository to clone the code, open Issues, or submit PRs, and build the next-generation data runtime environment with us!

Command → Domain transition → SQL → Audit diff → Event log → UI projection

The task board intentionally uses a tiny domain model so the runtime behavior is easy to follow. TeaQL itself is designed for significantly larger business domains, where understanding domain transitions, generated SQL, audit trails and query execution paths becomes even more important.

To make the idea concrete, we built a terminal-based Kanban board using Ratatui + SQLite. When you move a task from Planned to Ready, TeaQL shows the generated SQL, optimistic concurrency update, audit trail, lifecycle event, and refreshed status facets — all in real time.

The app also cross-compiles as a standalone statically linked binary for armv7 router environments, with no external runtime dependencies.

✨ Powered by native rusqlite: The TeaQL code generator natively supports rusqlite, producing 100% Rust-native SQLite execution code that compiles directly into your binary with zero external driver overhead.

Try it instantly in two ways:

• Hosted SaaS demo: open the multi-tenant Robot Task Board at lab-robot-task-board-rust.teaql.io. The hosted version is designed as a SaaS-style multi-tenant deployment, so different tenants can try the same TeaQL-powered task board without sharing one local database instance.
• Local Docker demo: run the server locally when you want to inspect the runtime behavior on your own machine.

docker run --rm -it teaql/robot-task-board:minimal

The demo app source is available at teaql/robot-task-board.

TeaQL for Rust​

TeaQL is coming to Rust.

We have now open-sourced the Rust-based TeaQL generator and runtime foundation. You can find the source code at teaql/teaql-forge-rs.

For a faster hands-on experience, run the server directly with Docker:

docker run -d --name teaql-forge-server -p 8080:8080 teaql/teaql-forge-rs:latest

The project is still in its early stage. Our goal is to explore how TeaQL's domain query model can work naturally in Rust, and how it can help developers build domain-driven business applications with clearer models, safer queries, and better local tooling.

The early open-source line will focus on:

• a lightweight TeaQL generator for Rust
• basic domain model definitions
• query model and request structures
• runtime foundation for local execution
• simple examples and demo applications
• a developer-friendly project structure for the Rust ecosystem

This project is not intended to be a large framework from day one. We want to start small, make the basic ideas clear, and let developers understand how TeaQL can fit into Rust projects naturally. The early version will focus on clarity, simplicity, and practical usage.

Rust is a good fit for TeaQL's next step because it provides strong type safety, high performance, local-first deployment, single-binary distribution, good support for CLI and developer tools, and a growing ecosystem for business and infrastructure software.

TeaQL for Rust is an open-source Rust-based direction for TeaQL, starting with a lightweight generator and runtime foundation for building domain-driven business applications.

For this task board demo, the TeaQL runtime crates, generated Rust code, and Rust-focused generator foundation are open source. The source code is available at teaql/teaql-forge-rs, and the Docker image above gives you the quickest way to try the server.

📁 Project Structure​

robot-task-board/
├── src/
│   ├── app.rs           # Core Application State
│   ├── commands.rs      # User command parsing (`/add`, `/mv`, etc)
│   ├── logging.rs       # TeaQL Audit Sink & Logging extensions
│   ├── main.rs          # Event loop & application entry point
│   ├── models.rs        # Lightweight models & DTOs for the UI
│   ├── service.rs       # Domain behavior, Aggregate Roots & TeaQL queries
│   ├── startup.rs       # Animated startup / bootstrap rendering
│   ├── tui.rs           # Terminal initialization and restoration
│   ├── ui.rs            # Ratatui layout, syntax-highlighted log rendering
│   └── utils.rs         # System info (CPU/memory) from /proc
├── models/
│   └── model.xml        # Generated by AI via teaql-agent-kit (https://github.com/teaql/teaql-agent-kit), validated & auto-healed via the `teaql eval` command
├── generate-lib/
│   └── lib/             # Auto-generated TeaQL domain library (Generated via `teaql gen-lib models/model.xml`)
├── Cargo.toml
└── README.md

🔬 Why TeaQL? (10 Applied Scenarios)​

This application exercises 10 distinct TeaQL capabilities across its CRUD and query workflows. Each scenario below maps a TeaQL API to its concrete usage in this app and the exact SQL it produces.

Scenario 1: Schema Bootstrap (ensure_rusqlite_schema_for)​

What it does: Automatically creates or migrates all database tables and seeds initial reference data (status values, platform) from the domain model — zero manual SQL.

// service.rs — One-line schema setup
let mut ctx = robot_kanban::module_with_behaviors_and_checkers().into_context();
ctx.use_rusqlite_provider(inner_executor.clone());
ensure_rusqlite_schema_for(&ctx)?;

Applied in: TaskService::new() — on first run, creates task_data, task_status_data, and platform_data tables with seed data; on subsequent runs, applies any schema changes from the model.

Bonus (Sample Data): Beyond schema creation, the framework also auto-generates a sample_data module from your model. This allows developers to inject structured, type-safe mock entities with a single function call for rapid prototyping and unit testing, without writing a single raw INSERT statement:

// Scaffold a batch of dummy tasks and execution logs in one line
robot_kanban::generate_sample_data(&ctx, SampleDataPlan::small()).await?;

Scenario 2: JSON-Based Dynamic Filtering (filter_with_json)​

What it does: Accepts a JSON object to dynamically construct WHERE clauses at runtime. An empty {} acts as a wildcard (no filter), enabling a single code path for both search and full-load.

// service.rs — Unified search/load query
let search_json = if let Some(ref term) = search_term {
    let escaped_name = serde_json::Value::String(term.clone());
    format!(r#"{{"name": {}}}"#, escaped_name)   // → {"name": "calibrate"}
} else {
    r#"{}"#.to_owned()                            // → {} (wildcard)
};

let select = Q::tasks().filter_with_json(&search_json);

Applied in: /search or /s command — filters the Kanban board in real-time.

Scenario 3: Faceted Aggregation (facet_by_status_as)​

What it does: Attaches a sub-query that computes aggregate counts grouped by a relation (status), all within a single database round-trip alongside the main entity query.

// service.rs — Single query fetches tasks + status counts
let select = Q::tasks()
    .comment(search_comment)
    .filter_with_json(&search_json)
    .facet_by_status_as("status_stats",
        // This sub-query could easily be extracted into a semantic helper method
        // e.g. `TaskStatusRequest::build_count_stats()` for reuse across the app
        Q::task_status().comment("Count status").count_tasks()
    );

let all_tasks = select
    .comment("Query tasks").purpose("Load data").execute_for_list(&self.ctx).await?;

// Access facet results from the same SmartList
if let Some(facet_list) = all_tasks.facet("status_stats") {
    for record in facet_list.iter() {
        let status_id = record.get("id");
        let count = record.get("count_tasks");
    }
}

💡 Pro Tip (Semantic Encapsulation): Notice how Q::task_status().count_tasks() is passed directly. Because TeaQL queries are strongly-typed data structures, you can effortlessly extract these aggregations into reusable, semantic helper methods.

// 1. Encapsulate the query logic into a reusable semantic method
impl TaskStatusRequest {
    pub fn build_count_stats() -> Self {
        Q::task_status().comment("Count status").count_tasks()
    }
}

// 2. Compose it cleanly in your main business logic
let select = Q::tasks()
    .filter_with_json(&search_json)
    .facet_by_status_as("status_stats", TaskStatusRequest::build_count_stats());

This allows you to compose massive, multi-layered TeaQL queries dynamically without polluting your business logic. (Note: The E:: Expression API provides the exact same composability for field-level conditions and evaluations!)

Generated SQL (3 queries in one round-trip):

-- 1. Main entity query
SELECT id, name, version, status AS status_id, platform AS platform_id
  FROM task_data WHERE (version > 0)
-- 2. Facet: load status reference data
SELECT id, name, code, color, display_order, progress, version FROM task_status_data WHERE (version > 0)
-- 3. Facet: aggregate task counts per status
SELECT status, COUNT(*) AS count_tasks
  FROM task_data WHERE (version > 0) AND (version > 0) AND (status IN (1, 1001, 1002, 1003, 1004)) GROUP BY status

Applied in: Board reload — the Planned/Process/Done count badges and task lists are all populated from this single query.

Scenario 4: Entity Factory (Q::tasks().comment("Create tasks").new_entity())​

What it does: Creates a new entity instance pre-wired with the runtime context, ready for field population and persistence.

// task/logic.rs — Encapsulated factory method with DDD validation
impl Task {
    pub fn create(cmd: &CreateTaskCommand, next_id: u64, ctx: &UserContext) -> Result<Self, AppError> {
        let mut task = Q::tasks().comment("Create tasks").new_entity(ctx);
        task.update_id(next_id)
            .update_name(cmd.name.clone())
            .update_version(1_i64)
            .update_status_to_planned()  // Safe API: raw update_status_id(1) is blocked by the compiler
            .update_platform_id(1_u64);
        Ok(task)
    }
}

Generated SQL:

INSERT INTO task_data (id, name, version, status, platform)
  VALUES (1, 'calibrate sensor', 1, 1, 1)

Applied in: bare input <name> or /add command — creates a new task in Planned status.

Scenario 5: ID Space Generation (RusqliteIdSpaceGenerator)​

What it does: Generates globally unique, monotonically increasing IDs per entity type using a dedicated SQLite sequence table — no auto-increment column needed.

// service.rs — add_task()
let next_id = self.ctx.next_id_for::<Task>()?;

Applied in: bare input <name> or /add command — each new task receives a unique ID from the Task ID space.

💡 Pro Tip: The Universal UserContext Notice how we retrieve the ID generator from self.ctx? The UserContext object is pervasive throughout your application's domain layer and request lifecycle. Because it is visible everywhere, it acts as the perfect dependency injection container.

You can integrate any external resources directly into UserContext, such as:

• Redis caching layers
• External API clients
• Email / SMS service clients
• Internationalization (i18n) resources

Simply use ctx.insert_resource(...) at initialization, and use extension traits to expose type-safe, domain-specific methods anywhere in your business logic.

Scenario 6: Domain Behavior & Cascading Save (DDD Aggregate Root)​

What it does: Allows attaching rich domain logic directly to generated entities using Rust's Native Extension Traits, and securely saving the entire Aggregate Root graph in a single atomic transaction.

// service.rs — Executing a DDD behavior
let mut task = Q::tasks().comment("Query tasks").purpose("Load data").with_id_is(id).comment("Query task_status").purpose("Load data").execute_for_one(&self.ctx).await?;

// 1. Invoke pure domain method (updates internal state)
let next_status = task.transition_status(&cmd)?;

// 2. Generate a child log entity via domain behavior
let log = task.generate_execution_log("STATUS_CHANGED", &detail, &self.ctx);

// 3. Attach the child to the Aggregate Root's collection
task.task_execution_log_list_mut().push(log);
task.set_comment("Move task status");

// 4. Graph persistence: Recursively saves the Task AND inserts the new child Log!
task.save(&self.ctx).await?;

Applied in: /mv command — enabling clean, expressive state mutations directly on Task objects.

Scenario 7: Partial Projections & Aggregations (return_type::<T>())​

What it does: Tells TeaQL to deserialize query results into a custom data transfer object (DTO) instead of the default generated entity. This is vital when executing partial selects or complex groupings where the returned shape no longer matches the full entity.

// Define a custom DTO for aggregations or partial fields
#[derive(TeaqlEntity)]
pub struct StatusStats {
    pub status: i32,
    pub task_count: i64,
}

// Fetch custom projection instead of raw Task
let stats = Q::tasks().select_status()
    .count_id_as("task_count")
    .group_by_status()
    .return_type::<StatusStats>()
    .comment("Query tasks").purpose("Load data")
    .execute_for_list(&ctx).await?;

Applied in: High-performance dashboard rendering — avoids full-entity deserialization overhead when projecting lightweight summaries or grouped counts.

Scenario 8: Audited Soft-Delete (mark_as_delete)​

What it does: Deletes an entity using the rich domain object rather than raw IDs. By chaining mark_as_delete() and set_comment() directly on the entity, TeaQL enforces optimistic concurrency (via the entity's current version) and gracefully propagates the deletion context to the EntityEventSink for audit logging.

// service.rs — delete_task()
let task_name = task.name().to_string();
task.mark_as_delete().set_comment(format!("Delete task '{}'", task_name));
task.save(&self.ctx).await?;

Generated SQL:

UPDATE task_data SET version = -2 WHERE id = 1 AND version = 1

TeaQL uses a soft-delete pattern — version is set to a negative value rather than removing the row, preserving audit history.

Applied in: /del command.

Scenario 9: Comment Chain Propagation (.comment())​

What it does: Attaches human-readable intent annotations to queries. When queries have nested sub-queries (e.g., facets), comments propagate down the chain with -> separators, creating a full trace of query intent.

// service.rs — Comments propagate through facet sub-queries
let select = Q::tasks()
    .comment("Get active tasks")                       // Parent comment
    .filter_with_json(&search_json)
    .facet_by_status_as("status_stats",
        Q::task_status().comment("Count status")       // Child comment
            .count_tasks()
    );

Resulting log trace chain:

[Get active tasks]                                → main task query
[Get active tasks->status_stats->Count status]    → facet status lookup
[Get active tasks->status_stats->Count status]    → facet aggregate count

The TUI renders these traces in real-time with syntax-highlighted colors — timestamp, user context ([philip]), comment chains, result summaries, and elapsed times are each distinctly colored:

[12:06:00.225]-[philip]-[0.184ms]-[DEBUG]-SqlLogEntry - [Get active tasks] - [5*Task] SELECT ... 
[12:06:00.226]-[philip]-[0.138ms]-[DEBUG]-SqlLogEntry - [Get active tasks->status_stats->Count status] - [3*TaskStatus] SELECT ... 

Applied in: Every query in the application — enables real-time SQL auditing from the TUI log panel.

Scenario 10: Entity Audit Subsystem (EntityEventSink)​

What it does: TeaQL automatically hooks into the persistence lifecycle to track fine-grained Entity Events (Create, Update, Delete, Recover) and computes precise field-level diffs (old_value ➔ new_value).

// logging.rs — Implement the sink to intercept framework audit events
pub struct AppAuditSink;

impl EntityEventSink for AppAuditSink {
    fn on_event(&self, ctx: &UserContext, event: &EntityEvent) -> Result<(), RuntimeError> {
        let user = short_user(ctx);
        // ... format changes and output to TUI Log Area and app.log
        for change in &event.changes {
            let detail_line = format!(
                "[{}]-[{}]-[AUDIT]-  -> Field [{}]: {} ➔ {}",
                timestamp, user, change.field, change.old_value, change.new_value
            );
        }
        Ok(())
    }
}

// Attach it during runtime initialization
ctx.set_event_sink(AppAuditSink);

Resulting log output:

[12:04:23.529]-[philip]-[AUDIT]-Entity [Task(1)] was UPDATED. [Move task 'My New Task' status from PLANNED to READY]
[12:04:23.529]-[philip]-[AUDIT]-  -> Field [status]: PLANNED ➔ READY
[12:04:23.529]-[philip]-[AUDIT]-  -> Field [version]: 1 ➔ 2
[12:04:23.530]-[philip]-[AUDIT]-Entity [TaskExecutionLog(2)] was CREATED. [Move task 'My New Task' status from PLANNED to READY]

Next Steps / Coming Soon: In the next phase, we will introduce the audit ignore feature. By adding an attribute in the model.xml, developers will be able to explicitly exclude sensitive data (like passwords, PII, or internal tokens) from being captured or diffed by the audit subsystem.

Scenario Summary​

📐 Architecture​

3-Layer Separation​

main.rs has no direct dependency on TeaQL types — it only interacts with TaskService, TaskModel, and MoveResult.

DDD Aggregate Root​

Generated Task entities act as Data Transfer Objects but are extended with native impl Task methods to encapsulate business logic:

• Task::create() — factory method with validation
• Task::transition_status() — automatic next-status resolution
• Task::generate_execution_log() — encapsulation of internal event generation

Domain Model​

Defined in models/model.xml, the TeaQL domain model declares two entities with a status relation:

<task_status
    name="Planned|Ready|Executing|Verified"
    code="PLANNED|READY|EXECUTING|VERIFIED"
    _features="status"
    _identified_by="code" />

<task
    name="Task Name|[1,200]"
    status="task_status()"
    _features="custom" />

🤖 Taming AI via Service-Generated APIs​

A hidden paradigm shift in this architecture is how naturally it tames AI coding assistants. The workflow forms a highly predictable closed loop:

1. AI Generation: An AI easily drafts the declarative domain model (model.xml) from raw business requirements. To automate this process entirely, we built the teaql-agent-kit.
2. Translation Service: A dedicated background service takes this model and translates it into a dense, strictly-typed Rust API layer.
3. High-Obedience Implementation: When the AI helps you write application logic, it relies entirely on these generated, compiler-enforced APIs.

This generated layer acts as an absolute guardrail against common AI hallucinations:

• Safe Setters (No Magic Numbers): Instead of task.update_status_id(1) (which is natively blocked by the compiler), the AI is forced to use the semantic task.update_status_to_planned(). It cannot hallucinate invalid foreign keys.
• Safe Getters (The E:: Expression API): Deeply nested or nullable data retrieval in Rust often causes AI to write buggy .unwrap() chains. TeaQL provides a monadic expression API:

  use robot_kanban::E;
  
  // Safe optional-chaining: swallows nulls gracefully and eliminates type mismatch
  let name = E::task_status(status).get_name().eval().unwrap_or(raw_str);
  

  The AI gets perfect auto-completion for legitimate fields (.get_name()) and produces zero runtime panics.

🛠 Commands​

Commands use a slash (/) prefix. Any bare text (without a slash) is treated as a quick-add for a new task.

⚙️ Prerequisites​

• Rust toolchain (1.70+)
• TeaQL Runtime Packages — the following crates are expected to be available (e.g., via relative path or git submodule):
  • teaql-core, teaql-runtime, teaql-macros, teaql-sql, teaql-provider-rusqlite

A Note on Open Source: The TeaQL Rust generator and runtime foundation are now open source at teaql/teaql-forge-rs. For a faster experience, you can also run docker run -d --name teaql-forge-server -p 8080:8080 teaql/teaql-forge-rs:latest and try the server directly.

• For cross-compilation: cargo-zigbuild and the armv7-unknown-linux-musleabihf target

Note: TeaQL runtime crates are published on crates.io. No local checkout is needed — cargo build will fetch them automatically.

🚀 Build & Run​

Local Development​

# Check compilation
cargo check

# Run the TUI
cargo run

# Run the TUI in compact mode (hides the SQL log area)
cargo run -- -c

# Build optimized release binary
cargo build --release

ARMv7 Cross-Compilation​

# Static cross-compile for armv7 routers
cargo zigbuild --release --target armv7-unknown-linux-musleabihf

The output binary is at target/armv7-unknown-linux-musleabihf/release/robot-task-board — upload directly to a router and run with zero dependencies.

Running Tests​

cargo test

Tests cover:

• Comment propagation — verifies TeaQL comment chains propagate through facet sub-queries
• CRUD lifecycle — add → reload → verify → delete → verify
• DDD transitions — Planned → Ready → Executing → Verified with automatic and explicit status moves

💬 What We'd Love Feedback On​

We're building TeaQL because we believe developers shouldn't have to choose between clean Domain-Driven Design and raw SQL performance/visibility.

If you try out this Kanban board or look at the code:

• Does the query tracing (.comment()) actually help you understand what the app is doing?
• How do you feel about defining your domain in model.xml vs writing Rust structs directly? We'd love your thoughts on the DX of declarative modeling.
• Upcoming Feature: We are working on an audit ignore attribute to exclude PII/sensitive data from the EntityEventSink. How do you currently handle this in your stack?

Drop a comment on HN, open an issue, or reach out!

(P.S. TeaQL was originally born out of our need to manage complex workflows and data at scale. Check out the framework behind this at teaql.io — if you're building physical infra or complex business logic, come say hi!)

TeaQL 1.0.0 focuses on API Elegance, Developer Ergonomics, AI-Native Workflows, and Transaction Safety.

🌟 Major Highlights​

1. Ultra-Elegant Native Chained Mutations (Zero-Repo)​

We have completely phased out raw repository-level guard classes (e.g., QueryCommentGuard). Operations on entities are now performed entirely via pure, fluent, object-oriented method chaining on the generated entities themselves.

• Before: Manual context building, repository lookups, and passing guards.
• After (Rust/Java):

  // Beautiful, domain-driven API
  task.update_status_to_planned()
      .set_comment("Start working on feature X")
      .audit_as("Save operation").save(&ctx)
      .await?;
  

All persistence and graph relationship merging happens automatically under the hood via the newly stabilized entity.audit_as("Save operation").save(&ctx) method.

2. Complete Transaction & Topological Safety​

• Postgres ID Generation Race Fixed: The core graph engine now correctly analyzes dependency topology. Entities are inserted in the exact required order (e.g., Product before OrderLine), ensuring foreign-key relationships are established perfectly and IDs are generated without race conditions.
• Java @Transactional Integration: Large operations like sample data generation are now wrapped in a single, unified transaction context. This provides a massive performance boost (thousands of inserts in milliseconds) and ensures atomic rollbacks.
• Rust QueryExecutor Stability: Deep integration with SQLx ensures that entity.audit_as("Save operation").save(&ctx) intelligently triggers begin_transaction and commit_transaction, handling complex graph-writes as a single atomic unit.

3. API Naming Convention Modernization (which_ ➡️ with_)​

To improve semantic clarity and readability, all query filtering methods have been renamed from which_* to with_*.

• which_name_contains -> with_name_contains
• which_status_is -> with_status_is

This change makes complex queries read exactly like natural language.

4. AI-First Architecture (AGENTS.md)​

TeaQL 1.0.0 is the first framework built with AI-Coding agents in mind. Our code generators now emit an AGENTS.md file designed to directly instruct LLMs (like Cursor, GitHub Copilot, and Claude) on your project's data architecture, constraints, and Red Lines (e.g., mandatory audit logging requirements via .set_comment()).

🐞 Bug Fixes & Core Improvements​

• Macro Stability: Cleaned up outdated attach_root_recursive generation logic in teaql-macros.
• Date/Timestamp Parsing: Fixed edge-case bugs in Text-to-Date and Timestamp conversions.
• Version Updates: Fixed issues where version fields were incorrectly skipped during optimistic locking updates.
• Inverse Relations: Added robust support for resolving both one-to-many and one-to-one inverse relations during relation loading.
• Schema Migration: Stripped identifier quotes before comparing columns to prevent unnecessary migrations on MySQL/Postgres.

⚠️ Breaking Changes​

1. Repository Access: Manual instantiation of TaskRepository or QueryCommentGuard is strictly deprecated and removed. Use .audit_as("Save operation").save(&ctx) on the entity.
2. Query Prefixes: Any existing code using which_ must be updated to use with_.
3. Audit Log Enforcement: Calling .audit_as("Save operation").save(&ctx) on core entities will now strictly mandate the presence of an audit comment via .set_comment().

📦 Upgrading​

For Rust users: Update your Cargo.toml:

teaql-core = "1.0.0"
teaql-macros = "1.0.0"
teaql-runtime = "1.0.0"
teaql-provider-sqlx-postgres = "1.0.0"

For Java/Spring Boot users: Update your Maven/Gradle plugin version to 1.0.0 and regenerate your project.

Thank you to all contributors who helped test the beta versions leading up to 1.0.0! Happy coding! ☕

A developer writes a useful request:

Q.candidates().selectName()
    .selectEmail()
    .filterBySkill("Java")
    .page(1, 20)
    .comment("Query candidates").purpose("Load data")
    .executeForList(ctx);

The request looks typed, generated, and harmless. But in a platform like Multi Talent, a candidate belongs to a customer account, a workspace, a recruiter team, and often a legal region. A useful query becomes unsafe if it can see outside those boundaries.

That is why TeaQL treats request execution as a runtime boundary, not just a method call.

The Multi Talent Problem​

Imagine Multi Talent as a SaaS platform for recruiting agencies and enterprise hiring teams.

The same TeaQL model may include:

• candidates;
• talent profiles;
• resumes and attachments;
• interview records;
• offer workflows;
• customer accounts;
• recruiter teams;
• regional compliance metadata.

The query language should stay expressive. A team should be able to search candidates by skill, location, availability, interview status, and related job opening.

But every query must also respect infrastructure and customer boundaries:

• customer A must never read customer B's candidates;
• a recruiter can only see candidates assigned to their team or allowed pool;
• regional data residency policy may limit which records can be loaded;
• raw SQL escape hatches should not bypass tenant rules;
• unlimited list requests should not become infrastructure abuse.

Those rules should not be copied into every controller.

The Wrong Place for the Rule​

One option is to add filters wherever a query is written:

Q.candidates().filterByCustomer(ctx.currentCustomer())
    .filterByRecruiterTeam(ctx.currentTeam())
    .filterBySkill("Java")
    .comment("Query candidates").purpose("Load data")
    .executeForList(ctx);

This works until one path forgets the filter. It also asks every feature author to understand every infrastructure and data-protection rule.

Another option is to hide the query behind service methods. That can work for some workflows, but TeaQL deliberately gives teams a generated request language. The runtime should make that language safe instead of forcing teams to abandon it.

The Runtime Boundary​

TeaQL Java runtime exposes a dedicated UserContext extension point for this final step:

protected <T extends Entity> SearchRequest<T> enforceRequestPolicy(SearchRequest<T> request) {
    return request;
}

Every normal request execution path goes through this hook before the request is submitted to the repository:

SearchRequest
  -> UserContext
  -> enforceRequestPolicy(...)
  -> Repository
  -> database provider

That placement matters. It is late enough to see the actual request that is about to execute, but still early enough to change it or reject it.

TeaQL Rust has the same runtime-boundary idea through RequestPolicy on UserContext. The Rust hook is platform-scoped and runs after entity-scoped repository behavior, so it can make the final decision before the request reaches the provider.

A Multi Talent Policy​

A Multi Talent project can extend its generated context and enforce the policy once:

public class MultiTalentUserContext extends MultiTalentGeneratedUserContext {

    @Override
    protected <T extends Entity> SearchRequest<T> enforceRequestPolicy(SearchRequest<T> request) {
        request = super.enforceRequestPolicy(request);

        String type = request.getTypeName();

        if ("Candidate".equals(type) || "TalentProfile".equals(type)) {
            request.appendSearchCriteria(
                    request.createBasicSearchCriteria(
                            "customerAccount",
                            Operator.EQUAL,
                            currentCustomerAccount()));

            request.appendSearchCriteria(
                    request.createBasicSearchCriteria(
                            "recruiterTeam",
                            Operator.IN,
                            visibleRecruiterTeams()));
        }

        if ("ResumeAttachment".equals(type)) {
            enforceRegionalAccess(type);
        }

        rejectDangerousRequestShape(request);
        auditSensitiveRead(request);

        return request;
    }
}

The example is intentionally centralized. Feature code can still express the business query:

Q.candidates().selectName()
    .selectEmail()
    .filterBySkill("Java")
    .page(1, 20)
    .comment("Query candidates").purpose("Load data")
    .executeForList(ctx);

The runtime adds the customer and team boundaries before the repository sees the request.

Protecting More Than Rows​

The hook is not only about tenant IDs.

In a real platform, request policy can protect infrastructure as well as data:

• reject rawSql for normal users;
• cap page size for list views;
• block unlimited() on high-volume entities;
• add region or data residency predicates;
• require extra audit for sensitive reads;
• remove unsafe relation loading for restricted roles;
• attach request comments or markers for tracing.

For example:

private void rejectDangerousRequestShape(SearchRequest<?> request) {
    if (request.getRawSql() != null && !currentUserCanUseRawSql()) {
        throw new AccessDeniedException("Raw SQL is not allowed for this user");
    }

    Slice slice = request.getSlice();
    if (slice != null && slice.getSize() > 200) {
        slice.setSize(200);
    }
}

This is infrastructure protection. It prevents one feature path from turning into a full-table scan, an accidental data export, or an expensive cross-tenant aggregation.

Why UserContext Is the Right Place​

UserContext already knows the runtime facts needed to enforce policy:

• the current customer or tenant;
• the current operator;
• roles, teams, and permissions;
• request headers and trace ID;
• client IP and proxy chain;
• environment-level beans and services;
• audit and logging services.

Repositories should not need to know every business permission model. Controllers should not need to repeat low-level safety rules. The generated request API should remain readable.

UserContext is the convergence point.

Auditing Sensitive Reads​

Because the hook sees the final request, it is also a useful place to audit sensitive reads:

private void auditSensitiveRead(SearchRequest<?> request) {
    if (!"Candidate".equals(request.getTypeName())) {
        return;
    }

    auditTrail().recordRead(
            traceId(),
            currentCustomerAccountId(),
            currentUserId(),
            request.getTypeName(),
            request.comment(),
            getClientIp());
}

This does not replace business-level audit records such as "approved offer" or "revoked recruiter access." It complements them by making sensitive data access observable at the runtime boundary.

The Design Principle​

Generated APIs should make business intent visible.

Runtime policy should make that intent safe to execute.

In Multi Talent, a query for candidates should read like a query for candidates. It should not be filled with repeated customer, team, residency, audit, and infrastructure rules. Those rules belong at the boundary where a request is submitted to the runtime.

That is what enforceRequestPolicy is for.

In Rust, the same idea is expressed as a RequestPolicy:

use teaql_core::{Expr, SelectQuery};
use teaql_runtime::{RequestPolicy, RuntimeError, UserContext};

pub struct MultiTalentPolicy;

impl RequestPolicy for MultiTalentPolicy {
    fn enforce_select(
        &self,
        ctx: &UserContext,
        query: &mut SelectQuery,
    ) -> Result<(), RuntimeError> {
        if matches!(query.entity.as_str(), "Candidate" | "TalentProfile") {
            let customer_id = ctx
                .get_named_resource::<u64>("customer_account_id")
                .copied()
                .ok_or_else(|| RuntimeError::Policy("missing customer account".to_owned()))?;

            let tenant_filter = Expr::eq("customer_account_id", customer_id);
            query.filter = Some(match query.filter.take() {
                Some(existing) => existing.and_expr(tenant_filter),
                None => tenant_filter,
            });
        }

        if query.raw_sql.is_some() {
            return Err(RuntimeError::Policy(
                "raw SQL is not allowed for normal users".to_owned(),
            ));
        }

        Ok(())
    }
}

Register it during runtime assembly:

let ctx = teaql_runtime::UserContext::new()
    .with_module(multi_talent::module_with_behaviors_and_checkers())
    .with_request_policy(MultiTalentPolicy);

Java uses UserContext.enforceRequestPolicy. Rust uses RequestPolicy. The design principle is the same: TeaQL projects get a final, explicit place to protect the platform and the customer's data before a request reaches the repository.

That happens easily in data-heavy systems. The model may be discussed in design sessions, but implementation code becomes SQL strings, mapper files, repository methods, DTOs, and service glue.

TeaQL uses generated APIs to keep the domain model visible.

Model First​

TeaQL starts from a domain model:

• entities;
• scalar fields;
• object relations;
• child lists;
• constants;
• validation expectations;
• data-service targets.

The generator turns that model into APIs. Application code then works with the generated vocabulary instead of reconstructing it by hand.

Queries as Domain Language​

Generated query methods make intent explicit:

Q.orders().filterByMerchant(ctx.getMerchant())
    .selectCustomer(Q.customers().comment("Query customers").purpose("Load data").selectName())
    .selectLineItemList(Q.lineItems().selectSku().selectQuantity())
    .countLineItems()
    .comment("Query orders").purpose("Load data")
    .executeForList(ctx);

The code names the domain structure:

• orders;
• merchant;
• customer;
• line items;
• SKU;
• quantity.

That is more reviewable than a service method that hides several mapper calls and response transformations.

Relations Matter​

DDD systems are rarely flat. Relations carry meaning:

• an order has line items;
• a merchant belongs to a platform;
• an employee belongs to a department;
• a ticket has comments and assignments.

TeaQL relation loading APIs give those relationships a generated shape. The runtime can still decide how to execute the load efficiently.

Graph Writes​

Domain changes often arrive as object graphs:

• create an order with lines;
• update a parent and merge children;
• remove a child row;
• attach an existing reference;
• keep missing children for a relation that should not delete absent rows.

TeaQL Rust models this through graph nodes, graph operation state, mutation planning, and transaction boundaries. Java TeaQL carries the same high-level idea through entity save and graph-oriented runtime behavior.

Validation and Runtime Policy​

Domain logic is not only data shape. It also includes:

• required fields;
• status transitions;
• tenant rules;
• permission policy;
• audit metadata;
• language-aware validation messages.

TeaQL keeps those concerns near runtime context and generated model hooks instead of scattering them across controllers.

Why Generate?​

Handwritten domain APIs are possible. The problem is consistency.

Generation gives every entity the same baseline:

• field selectors;
• filters;
• relation selectors;
• aggregate helpers;
• request builders;
• checker hooks;
• behavior hooks;
• runtime registration.

Teams can then focus on the parts of the domain that are actually special.

The Short Version​

Generated APIs are not a shortcut around domain modeling.

They are a way to make the domain model executable, reviewable, and reusable across application code, runtime providers, and AI coding tools.

That description is incomplete.

TeaQL is a generated business API layer. Persistence is one part of the system, but the main value is the generated domain language that sits above persistence.

What an ORM Usually Optimizes​

Most ORM discussions focus on mapping:

• classes to tables;
• fields to columns;
• relations to joins;
• objects to rows;
• transactions to persistence sessions.

Those are real problems. TeaQL also needs to solve them. But large business systems have another repeated problem: the same business request is rebuilt again and again in controllers, repositories, DTOs, SQL, validators, and frontend response logic.

What TeaQL Optimizes​

TeaQL optimizes the business API surface.

It generates request APIs that can express:

• selection;
• nested relation loading;
• filters;
• list-existence queries;
• pagination;
• grouped statistics;
• relation aggregates;
• graph writes;
• validation hooks;
• runtime customization.

The generated API is meant to be read by backend engineers, domain engineers, reviewers, and AI coding tools.

Generated Business APIs​

An ORM might make it easy to load an Order.

TeaQL aims to make it clear how a complete order page is assembled:

Q.orders().filterByMerchant(ctx.getMerchant())
    .selectCustomer(Q.customers().comment("Query customers").purpose("Load data").selectName())
    .selectLineItemList(Q.lineItems().selectSku().selectQuantity())
    .countLineItems()
    .orderByCreateTimeDescending()
    .page(1, 20)
    .comment("Query orders").purpose("Load data")
    .executeForList(ctx);

The key is not whether this compiles to SQL. It does. The key is that the API names the business shape before the runtime turns it into storage operations.

Runtime Boundary​

TeaQL also treats runtime behavior as part of the model:

• user context;
• tenant and permission policy;
• cache behavior;
• distributed locks;
• logging and metrics;
• validation;
• event dispatch;
• database provider selection.

That is why TeaQL has a runtime layer instead of only a mapper layer.

Why This Helps AI​

AI tools should not need to guess SQL, join rules, table names, tenant filters, and response shapes from scattered code.

Generated APIs give AI tools a deterministic vocabulary:

• call this field selector;
• use this relation loader;
• compose this query fragment;
• execute through this runtime context;
• do not bypass the provider.

That is a different goal from a traditional ORM.

The Short Version​

TeaQL uses persistence mapping, but it is not defined by persistence mapping.

It is a generated business API platform that keeps domain intent visible while allowing the runtime provider to change underneath.

The application code should use the generated API. The runtime should decide how that API executes against PostgreSQL, MySQL, SQLite, embedded SQLite, or memory.

Provider Matrix​

PostgreSQL​

PostgreSQL is the strongest default for production backend systems that need:

• transactions;
• rich query behavior;
• grouped aggregation;
• Decimal/NUMERIC support;
• schema bootstrap;
• id-space generation;
• production database tooling.

TeaQL's SQLx PostgreSQL provider keeps PostgreSQL-specific execution behind the repository boundary.

MySQL​

MySQL remains common in enterprise business systems. TeaQL's SQLx MySQL provider is intended for teams that want generated business APIs while staying on a familiar MySQL backend.

This is especially useful when moving away from handwritten mapper-heavy persistence without moving the database first.

SQLite​

SQLite has two important TeaQL paths.

SQLx SQLite is useful for async local-first apps, integration tests, small services, and portable demos.

rusqlite is useful when synchronous embedded SQLite is a better fit:

• devices;
• routers;
• edge deployments;
• appliance controllers;
• local agent memory.

MemoryRepository​

Not every generated API test needs a database.

MemoryRepository gives TeaQL a no-database path for:

• unit tests;
• model validation;
• lightweight demos;
• fast runtime simulation.

The goal is to test generated API behavior without requiring a database server.

Runtime Assembly​

The provider is registered below UserContext:

Generated service crate
  -> RuntimeModule
  -> UserContext
  -> Repository API
  -> selected provider

Generated crates can expose helpers for module registration, behavior/checker registration, provider-backed runtime setup, and schema bootstrap.

Why Providers Matter​

Without a provider boundary, application code tends to mix business intent with database details.

With providers, the generated API remains stable:

Q::platforms().select_merchant_list_with(Q::merchants().comment("Query merchants").purpose("Load data").select_name())
    .comment("Query platforms").purpose("Load data")
    .execute_for_list(&ctx)
    .await?;

The runtime decides whether that request executes through PostgreSQL, MySQL, SQLite, rusqlite, or memory.

That is the point of TeaQL's multi-database runtime direction.

That shift matters.

Java proved the generated business API style. Rust turns that style into a runtime direction for PostgreSQL, MySQL, SQLite, embedded SQLite, and memory-backed tests.

What Carries Over from Java​

The useful Java ideas are not Spring-specific. They are TeaQL-specific:

• generated Q APIs;
• readable query builders;
• field and relation selectors;
• SmartList style result metadata;
• runtime context;
• checker infrastructure;
• translated validation messages;
• mutation events;
• graph writes;
• relation enhancement;
• relation aggregate enhancement;
• safe value access.

Rust implements those ideas with Rust types, traits, crates, and provider registration.

What Does Not Carry Over Directly​

Some Java features should not be copied blindly:

• Spring Boot autoconfiguration;
• Java GraphQL generation;
• Java BaseService/controller conventions;
• reflection-style runtime mechanisms;
• the full Java database dialect matrix.

Rust needs a Rust-native shape. The runtime should be explicit, crate-based, and provider-backed.

The Rust Workspace​

The Rust runtime is split by responsibility:

• teaql-core for metadata, values, query model, entity traits, and SmartList<T>;
• teaql-sql for SQL compilation and dialect behavior;
• teaql-runtime for UserContext, repositories, checkers, events, relation enhancement, graph writes, and memory execution;
• teaql-macros for #[derive(TeaqlEntity)];
• provider crates for SQLx PostgreSQL, SQLx MySQL, SQLx SQLite, and rusqlite SQLite.

This keeps the core runtime separate from database adapters.

Generated Rust Crates​

teaql-code-gen can emit Rust service crates. A generated crate can include:

• entity structs;
• Q facade;
• generated request builders;
• behavior skeletons;
• checker skeletons;
• runtime module registration;
• repository and behavior registries;
• provider-backed runtime helpers.

Application code then uses generated APIs:

let platforms = Q::platforms().select_merchant_list_with(
        Q::merchants()
            .comment("Query merchants").purpose("Load data").select_name()
            .which_names_contain("TeaQL"),
    )
    .comment("Query platforms").purpose("Load data")
    .execute_for_list(&ctx)
    .await?;

Multi-database Runtime​

The Rust direction is provider-based:

• SQLx PostgreSQL for production-grade PostgreSQL backends;
• SQLx MySQL for common enterprise MySQL systems;
• SQLx SQLite for local-first apps, tests, and small services;
• rusqlite SQLite for embedded and multi-architecture deployments;
• MemoryRepository for no-database tests and demos.

The generated API should stay stable while the provider changes below it.

Current State​

The Rust runtime is already useful for core generated-domain paths:

• typed queries;
• relation loading;
• grouped aggregates;
• graph writes;
• checkers;
• events;
• schema bootstrap;
• SQL debug logs;
• generated high-level Q API validation against SQLite and PostgreSQL paths.

Full Java feature parity is not the only metric. The better metric is whether Rust has a coherent generated business API runtime.

That is now the direction.

The pressure appears when a business page needs more than one table and more than one query shape.

Consider an order page.

The Order Page Shape​

A typical order page may need:

• the order list;
• customer name;
• order status;
• line item preview;
• line item count;
• status counts for tabs;
• pagination;
• merchant or tenant filtering;
• permission-aware visibility.

With mapper-oriented persistence, this often becomes several mapper methods, XML fragments, DTO assembly, and post-query stitching.

The MyBatis Shape​

A MyBatis implementation might involve:

• one SQL query for the order list;
• one query or join for customer fields;
• one query for line item previews;
• one query for counts;
• one query for grouped status statistics;
• result maps or manual DTO mapping;
• service code to assemble the final response.

That is explicit and controllable, but the business intent is spread across files.

The TeaQL Shape​

TeaQL tries to express the page as one generated business request:

User userOrderInfo = Q.users()
    .comment("Query users").purpose("Load data").filterWithId(userId)
    .countOrder()
    .facetByOrderStatus("statusWithCount", Q.orderStatus().countOrders())
    .selectOrderList(
        Q.ordersWithId()
            .selectOrderId()
            .selectDate()
            .offset(0, 10)
            .selectLineItemList(
                Q.lineItemsWithId().selectImageURL().limit(3)
            )
            .countLineItems()
    )
    .execute(context);

The API is still explicit, but the explicitness is at the business level:

• user;
• orders;
• status counts;
• order list;
• line items;
• pagination;
• line item count.

What TeaQL Reduces​

TeaQL does not eliminate thinking. It reduces repetitive plumbing:

• mapper XML;
• duplicated DTO assembly;
• repeated relation-loading code;
• repeated count/statistics query fragments;
• stringly-typed field references;
• one-off page query services.

The generated model becomes the shared vocabulary.

Where MyBatis Still Wins​

MyBatis remains a good choice when:

• a query must be hand-tuned;
• SQL is the clearest expression of the business requirement;
• the domain model is small;
• teams need exact control over vendor-specific SQL;
• generated APIs would add weight without reducing repetition.

TeaQL and MyBatis do not need to be ideological opposites. TeaQL is valuable when the business model is large enough that generated APIs reduce repeated work.

The Review Difference​

In a TeaQL code review, the reviewer can ask:

• does this page select the correct relations?
• are the counts grouped correctly?
• is pagination applied at the right level?
• does the runtime context apply tenant and permission policy?

That is a higher-level review than checking XML fragments and DTO stitching.

The Short Version​

MyBatis gives direct SQL control. TeaQL gives generated business APIs.

For complex business pages, TeaQL keeps page intent closer to the domain model.

Instead of asking developers to repeatedly write repositories, SQL fragments, DTO stitching, relation loading code, and validation glue, TeaQL starts from a domain model and generates APIs that read like business intent.

The current positioning is simple:

Generated Business APIs. Java-proven. Rust-powered. Multi-database ready.

The Core Idea​

TeaQL separates the business API from the runtime provider.

Domain Model
  -> TeaQL Generator
  -> Generated Q API
  -> Runtime Provider
  -> MySQL / PostgreSQL / SQLite / Memory / Edge / Agent

Application code should talk to generated APIs. Runtime code should decide how those APIs execute against a database, memory repository, embedded store, or service runtime.

What TeaQL Generates​

Depending on the target stack, TeaQL can generate:

• entity types;
• query builders;
• safe expression helpers;
• relation loading helpers;
• checker and behavior skeletons;
• graph save entrypoints;
• runtime module registration;
• agent guidance for generated APIs.

In Java, this appears as fluent generated request APIs. In Rust, generated crates expose Q::entities() style query builders over teaql-rs.

Why It Matters​

Large business systems repeat the same concepts across many screens and services:

• users and roles;
• orders and line items;
• customers and accounts;
• status counts and dashboards;
• parent-child graph saves;
• tenant, permission, audit, and localization policies.

Without a generated business API layer, those concepts spread across SQL, mapper XML, repositories, service methods, DTOs, validators, and frontend-specific response shaping.

TeaQL keeps the model vocabulary visible in the code path.

Java and Rust​

Java TeaQL is the mature, proven path for enterprise systems and Spring Boot services.

Rust TeaQL is the runtime direction for generated domain APIs across PostgreSQL, MySQL, SQLite, embedded SQLite, and memory-backed tests.

The two stacks are not identical, and they do not need to be. They share the programming model: generated APIs over a domain model, executed through a runtime boundary.

A Small Example​

User userOrderInfo = Q.users()
    .comment("Query users").purpose("Load data").filterWithId(userId)
    .countOrder()
    .statsFromOrder("statusWithCount", Q.orders().comment("Query orders").purpose("Load data").count().groupByOrderStatus())
    .selectOrderList(
        Q.ordersWithId()
            .selectOrderId()
            .selectDate()
            .offset(0, 10)
            .countLineItems()
    )
    .execute(context);

This is not just a query. It is the shape of a business page expressed through generated APIs.

TeaQL in One Sentence​

TeaQL turns domain models into stable business APIs that humans and AI tools can read, compose, and run across Java, Rust, and multiple database providers.

If an AI tool has to infer persistence behavior from scattered SQL, repositories, mapper XML, DTOs, and service conventions, it will eventually guess wrong.

TeaQL exists to make that boundary deterministic.

The Guessing Problem​

When AI writes data-access code directly, it must infer:

• table names;
• column names;
• relation cardinality;
• tenant filters;
• permission rules;
• deleted-row semantics;
• transaction boundaries;
• pagination rules;
• response shape;
• database dialect differences.

Some of these guesses can pass a simple test and still be wrong in production.

The Business API Boundary​

TeaQL generates APIs from the domain model. That means AI code can compose with named business methods instead of inventing storage behavior.

let orders = Q::orders().select_customer_with(Q::customers().comment("Query customers").purpose("Load data").select_name())
    .select_line_item_list_with(Q::line_items().comment("Query line_items").purpose("Load data").select_sku())
    .which_statuses_are("PAID")
    .page(1, 20)
    .comment("Query orders").purpose("Load data")
    .execute_for_list(&ctx)
    .await?;

The model controls what fields and relations exist. The runtime controls how the query executes. The AI composes within those boundaries.

Deterministic Does Not Mean Rigid​

A deterministic API can still be expressive:

• filters can be combined;
• relation loads can be nested;
• aggregates can be grouped;
• graph writes can save parent and child objects together;
• provider-specific behavior can be selected below the API.

The point is that the API surface is stable and reviewable.

Better Prompts​

TeaQL also makes prompts smaller.

Instead of giving an AI tool the entire schema, SQL examples, repository conventions, and DTO rules, a team can provide a generated API guide:

Use TeaQL Q APIs for reads.
Use generated relation selectors.
Execute through UserContext.
Do not write raw SQL unless explicitly requested.
Use graph save for parent-child persistence.

That is a stronger contract than a long explanation of database structure.

Runtime Safety​

The generated API is only half the story. Runtime boundaries matter too.

TeaQL keeps execution behind context and provider layers:

• Java uses UserContext as the runtime boundary.
• Rust uses teaql_runtime::UserContext, repository registries, behavior hooks, and provider registration.
• Database providers execute against PostgreSQL, MySQL, SQLite, rusqlite, or memory.

AI-generated application code should not own those decisions.

The Short Version​

AI tools are fast at composition. They are unreliable at reconstructing business rules from infrastructure code.

TeaQL gives them deterministic business APIs to compose.