DEV Community: Philip Z

Stop Giving Your AI Agent Raw SQL

Philip Z — Wed, 30 Sep 2026 15:15:57 +0000

The fastest way to connect an AI agent to application data is often a generic
SQL tool. Give the model a schema, accept a SQL string, run it, and return the
rows.

That is also where a prototype can quietly become a production security and
maintenance problem.

The model must understand physical table names, joins, nullable columns,
tenant boundaries, authorization rules, and mutation policy. Database details
become part of the prompt contract. A schema change can invalidate that
contract, and a broadly capable SQL tool exposes much more authority than most
business tasks require.

TeaQL takes a different approach:

Don't give your AI agent unrestricted SQL. Give it a typed business language.

The open-source @teaql/ai-sdk
adapter converts an explicit allowlist of business capabilities into native
Vercel AI SDK tools. The model sees operations such as
findSchoolsMissingContact and updateSchoolContactPhone. The server keeps the
TeaQL context, runtime resources, authorization state, credentials, and
internal failures.

The missing layer beneath an agent SDK

The Vercel AI SDK already provides the agent loop, tool calling, streaming,
model-provider integration, and UI primitives. TeaQL does not reproduce those
features. It supplies the governed business-data layer beneath them:

User conversation
  -> Vercel AI SDK agent
  -> typed TeaQL business tools
  -> UserContext, policy, audit and runtime services
  -> database

A generic SQL tool exposes an implementation mechanism:

const executeSql = tool({
  description: "Execute SQL against the application database",
  inputSchema: z.object({ sql: z.string() }),
  execute: async ({ sql }) => database.query(sql),
});

A TeaQL capability exposes an application operation:

const findSchoolsMissingContact = defineTeaQLCapability({
  name: 'findSchoolsMissingContact',
  description:
    'Find schools of a given type whose contact phone is explicitly null.',
  inputSchema: z.object({
    schoolType: z.enum(['PRIMARY', 'SECONDARY']),
  }),
  risk: 'read',
  execute: ({ context, input }) =>
    context
      .requireResource<SchoolRepository>('schoolRepository')
      .findMissingContact(input.schoolType),
});

The second tool does not ask the model to invent a table name, encode an enum
as the right database value, or decide which columns are safe to return. Its
name and schema describe a bounded business capability.

Deny by absence

createTeaQLTools receives the complete set of capabilities available to one
agent. A capability that is not passed to the function does not exist in the
AI SDK toolset.

const tools = createTeaQLTools({
  context,
  capabilities: [
    findSchoolsMissingContact,
    updateSchoolContactPhone,
  ],
});

An optional runtime allowlist can narrow that set for a particular user or
agent:

const readOnlyTools = createTeaQLTools({
  context,
  capabilities: schoolCapabilities,
  allow: ['findSchoolsMissingContact'],
});

Unknown allowlist names and duplicate capability names fail during startup.
They do not silently produce a weaker or unexpectedly empty policy.

This is intentionally different from generating five CRUD tools for every
entity. Large domains can contain hundreds of entities. Automatically exposing
every operation creates tool-selection noise and grants the agent authority it
does not need. TeaQL models the smaller set of operations that make sense for
the agent's job.

The model never receives `UserContext`

The input schema is model-visible. The TeaQL UserContext is not.

const context = new UserContext()
  .insertResource('dataService', dataService)
  .insertResource('authorization', authorization);

const tools = createTeaQLTools({ context, capabilities });

context is captured in the server-side execute closure. It carries trusted
runtime resources, identity and policy selected by the application. The model
cannot construct it, replace its data service, choose another tenant, or add a
permission through tool input.

This follows a broader TeaQL API rule: business execution receives one trusted
context; process-level runtime ownership and provider installation are not
mixed into model-generated parameters.

Approval and authorization solve different problems

A write capability can request AI SDK approval:

const updateSchoolContactPhone = defineTeaQLCapability({
  name: 'updateSchoolContactPhone',
  description:
    'Update one school contact phone with an explicit audit reason.',
  inputSchema: z.object({
    schoolId: z.number().int().positive(),
    contactPhone: z.string().min(5).max(40),
    auditReason: z.string().min(8).max(200),
  }),
  risk: 'write',
  needsApproval: true,
  execute: async ({ context, input }) => {
    const school = await loadSchool(context, input.schoolId);
    return school
      .updateContactPhone(input.contactPhone)
      .auditAs(input.auditReason)
      .save(context);
  },
});

Approval asks whether the user authorizes this proposed tool call.
Authorization asks whether the authenticated user is allowed to perform the
operation at all. Audit records what happened and why. Validation determines
whether the proposed state is legal.

These controls reinforce one another, but they are not interchangeable:

Agent proposes a write
  -> AI SDK approval
  -> TeaQL runtime authorization
  -> domain validation
  -> audited save
  -> persisted result

A prompt that says "do not update restricted schools" is useful guidance. It
is not a runtime permission boundary.

Preserve the persisted result

The included school example starts with a secondary school whose contact phone
is explicitly null and whose optimistic version is 1. After an approved,
audited update, the tool returns the persisted object with the new phone and
version 2:

Persisted result: {
  id: 1,
  name: 'Riverside Secondary School',
  schoolType: 'SECONDARY',
  contactPhone: '+1-555-0100',
  version: 2
}

Returning the authoritative persisted entity matters when a database assigns
an ID, a trigger or default supplies a value, or optimistic versioning changes
state. A write tool should not reconstruct a record from its input and pretend
that it represents the database result.

TeaQL also distinguishes loaded, explicit null, and not-loaded states. A
partially projected entity cannot safely collapse those states into ordinary
TypeScript undefined values.

Observe failures without leaking them

Tool execution emits lifecycle events that can feed structured logs or an
OpenTelemetry adapter:

const tools = createTeaQLTools({
  context,
  capabilities,
  onEvent: event => telemetry.record(event),
});

The default events include capability name, risk, tool-call ID and timing.
Inputs are excluded because they may contain sensitive business data.

When capability execution fails, server telemetry receives the original error.
The model receives a safe message such as:

The updateSchoolContactPhone business operation could not be completed.

Applications can map public error messages, but raw connection strings, SQL,
credentials and internal exception details remain on the server.

Native Vercel AI SDK integration

The resulting object is an AI SDK ToolSet and can be passed directly to an
agent:

import { UserContext } from '@teaql/teaql';
import { ToolLoopAgent } from 'ai';
import { createTeaQLTools } from '@teaql/ai-sdk';

const context = new UserContext()
  .insertResource('schoolRepository', repository);

const agent = new ToolLoopAgent({
  model: 'openai/gpt-5.4',
  instructions:
    'Use only the provided business tools. Never invent SQL or database fields.',
  tools: createTeaQLTools({
    context,
    capabilities: schoolCapabilities,
  }),
});

The adapter uses AI SDK schemas, metadata, execution and approval semantics.
It does not require the application to adopt a second agent loop.

Run the demonstration without an API key

The repository contains a deterministic school-management demonstration. It
uses in-memory SQLite, so no external database, model API key, or signup is
required:

git clone https://github.com/teaql/teaql-ai-sdk.git
cd teaql-ai-sdk
npm install
npm run example

The demonstration prints:

the two model-visible capabilities;
approval metadata on the write tool;
schools whose contact value is explicitly null;
lifecycle events;
the persisted version change;
the audit record.

The small SQLite repository is handwritten to keep the adapter demonstration
self-contained. In a generated TeaQL application, its implementation is
replaced by generated Q requests, entities, Save behavior and a Runtime Module.
The AI SDK adapter and its security boundary remain the same.

The package is published as
@teaql/ai-sdk and can be added
to an existing AI SDK application with:

npm install @teaql/ai-sdk @teaql/teaql ai zod

The GitHub repository remains the source for the complete SQLite demonstration,
release workflow and implementation history.

Start with TypeScript, preserve cross-runtime semantics

The initial adapter is TypeScript-first because the Vercel AI SDK is a
TypeScript ecosystem. TeaQL's larger responsibility is preserving one domain
language and equivalent runtime behavior across Java, Rust, TypeScript, Swift,
Python, .NET and Go.

The intended generation path is:

TeaQL domain model
  -> runtime entities and typed queries
  -> explicit agent capability manifest
  -> AI SDK tools
  -> MCP tools
  -> agent usage Markdown
  -> executable TeaQL Agent Kit verification

A TypeScript AI SDK application can execute capabilities locally through the
TeaQL TypeScript Runtime. The same capability manifest can later reach another
TeaQL runtime through MCP or the TeaQL Federal Protocol without teaching the
model seven unrelated database APIs.

What is available today

The first public repository includes:

native AI SDK ToolSet creation;
typed input and output schemas;
explicit capability and per-agent allowlists;
trusted server-side UserContext injection;
read, write and privileged risk metadata;
approval support;
safe error mapping;
lifecycle events for telemetry;
configuration validation;
five automated boundary tests;
a no-key SQLite demonstration;
a passing public GitHub Actions workflow.

Generator-produced capability definitions, the hosted interactive demo,
OpenTelemetry export and cross-runtime MCP execution remain follow-up work. The
project documents those limits rather than presenting a thin adapter as a
finished enterprise security system.

Try it and challenge the boundary

The most useful feedback is not whether another generic tool wrapper can be
added. It is whether the capability boundary remains understandable and
enforceable in a real application:

Which business operations should become tools?
When should an operation require approval?
Which data must never appear in a model-visible schema or trace?
How should capability manifests evolve with a domain model?
Which negative conformance tests would make the security claim credible?

The code, tests and runnable example are available at
teaql/teaql-ai-sdk. Related work is
maintained in the TeaQL TypeScript Runtime,
TeaQL Agent Kit, and
TeaQL Conformance.

TeaQL Was 2,000x Faster Than the Obvious SQLx Query—Here’s What Actually Happened

Philip Z — Wed, 30 Sep 2026 15:14:56 +0000

We recently measured two implementations of the same application request over
the MusicBrainz dataset:

Load the newest 100 recordings that have linked works, and load at most ten
work relations for each recording.

The controlled SQLx test returned the same 100 recordings, 103 relation rows,
103 links, 103 link types, and Work-ID checksum through both paths. One took
5,871.169 milliseconds. The other took 2.469 milliseconds—a 2,378×
difference inside SQLx itself.

TeaQL Rust previously completed the corresponding typed graph workload in
2.864 milliseconds. That does not mean TeaQL has a PostgreSQL driver 2,000×
faster than SQLx. The difference was the amount of work requested from the
database. The expert SQLx control proves it.

What TeaQL is

TeaQL is a model-driven application runtime. A semantic model generates
language-native Q APIs for queries, E APIs for loaded expressions, and governed
graph mutation APIs. The same model can target seven runtimes: Rust, Java,
TypeScript, Go, Swift, .NET, and Python.

Queries carry more than SQL structure. They retain relation bounds, loaded
state, tenant and authorization scope, version policy, and an operational
comment and purpose. That additional intent is what made this optimization
possible without turning application code into handcrafted SQL.

The obvious single-statement SQLx solution

A capable SQL developer may reach for a window function to express Top-N per
parent:

WITH ranked AS (
  SELECT relation.*,
         row_number() OVER (
           PARTITION BY relation.entity0
           ORDER BY relation.link_order ASC, relation.id DESC
         ) AS rn
  FROM l_recording_work relation
  WHERE relation.version > 0
), roots AS (
  SELECT recording.id
  FROM recording
  WHERE recording.version > 0
    AND EXISTS (
      SELECT 1 FROM ranked WHERE ranked.entity0 = recording.id
    )
  ORDER BY recording.id DESC
  LIMIT 100
)
SELECT ...
FROM roots
LEFT JOIN ranked
  ON ranked.entity0 = roots.id AND ranked.rn <= 10
LEFT JOIN link ...
LEFT JOIN link_type ...
LEFT JOIN work ...;

This is readable, set-oriented SQL. It is not an obviously careless query. It
also asks PostgreSQL to rank the complete relation population—about 2.7 million
rows in this fixture—before reducing the graph to 100 roots and 103 relations.

In the Rust SQLx control, the PostgreSQL median was 5,871.169 ms. An earlier
raw JDBC run measured 5,579.224 ms, confirming that changing the client library
does not remove the database work. DuckDB, whose vectorized analytical engine
fits this global-ranking shape better, completed the earlier query in
808.158 ms.

The business request carried a stronger bound

The corresponding TeaQL request describes a bounded object graph. In an
application, we can name and reuse each meaningful graph fragment instead of
repeating the whole nested request at every call site:

fn link_type_details() -> LinkTypeRequest {
    Q::link_types_minimal()
        .select_name()
        .select_description()
        .select_link_phrase()
}

fn link_details() -> LinkRequest {
    Q::links_minimal()
        .select_ended()
        .select_link_type_with(link_type_details())
}

fn recording_work_details() -> LRecordingWorkRequest {
    Q::l_recording_works_minimal()
        .select_link_order()
        .select_link_with(link_details())
        .select_entity1_with(Q::works_minimal().select_name())
        .order_by_link_order_asc()
        .order_by_id_desc()
        .limit(10)
}

Q::recordings_minimal()
    .select_name()
    .select_length()
    .have_l_recording_works()
    .select_l_recording_work_list_with(recording_work_details())
    .order_by_id_desc()
    .limit(100)
    .comment("what: load the MB03 recording-work graph")
    .purpose("why: render bounded recording-work details")
    .execute_for_list(&context)
    .await?;

The main request now reads as a composition of business-relevant graph
fragments. The helpers are ordinary typed Rust functions: they can be reused,
tested, extended, and combined like building blocks. They do not hide raw SQL
or switch to a second query system; each still returns a generated TeaQL query
selection that the runtime can govern as one request.

See the same TeaQL request fully expanded

Q::recordings_minimal()
    .select_name()
    .select_length()
    .have_l_recording_works()
    .select_l_recording_work_list_with(
        Q::l_recording_works_minimal()
            .select_link_order()
            .select_link_with(
                Q::links_minimal()
                    .select_ended()
                    .select_link_type_with(
                        Q::link_types_minimal()
                            .select_name()
                            .select_description()
                            .select_link_phrase(),
                    ),
            )
            .select_entity1_with(Q::works_minimal().select_name())
            .order_by_link_order_asc()
            .order_by_id_desc()
            .limit(10),
    )
    .order_by_id_desc()
    .limit(100)
    .comment("what: load the MB03 recording-work graph")
    .purpose("why: render bounded recording-work details")
    .execute_for_list(&amp;context)
    .await?;

The important information is not the Rust syntax. It is the request shape:

choose 100 matching roots;
load no more than ten ordered relations for each selected root;
hydrate only the referenced Link, LinkType, and Work objects;
preserve version, policy, comment, and purpose semantics throughout.

TeaQL can select the roots first and constrain relation loading to those roots.
It does not need to rank relations belonging to recordings that cannot appear
on this page.

The SQLx control explains the result

We then wrote the optimization explicitly in ordinary SQLx:

fetch the 100 root recording IDs;
pass those IDs to a second parameterized query;
rank only relations whose entity0 belongs to that root set;
join Link, LinkType, and Work for the bounded rows.

Using one initialized SQLx pool connection, three warmups, and ten sequential
measurements, the medians were:

Implementation	PostgreSQL median
SQLx, natural global-window statement	5,871.169 ms
SQLx, expert root-first two-stage plan	2.469 ms
TeaQL Rust, typed governed graph (separate retained run)	2.864 ms

The first two rows are the controlled 2,378× comparison. The TeaQL row comes
from a separate retained run and is context, not part of that ratio. It includes
generated typed requests, relation hydration, and identity-graph assembly; the
SQLx control decodes aggregate tuples.

How much code did each plan require?

We counted the physical non-blank lines that declare and execute each query.
Imports, connection setup, timing, result gates, and reporting were excluded;
embedded SQL was included because the application owns it.

Implementation	Query LOC
SQLx, natural global window	26
SQLx, expert root-first	34
TeaQL, typed graph request (fully expanded)	27

The numbers are deliberately unexciting: TeaQL is not winning through a tiny
code-golf example. Its fully expanded typed request is about the same size as
the natural SQL. The composed version moves reusable graph fragments out of the
call site; it improves local readability without pretending that their
definitions vanished. The important difference is what those lines preserve.
The expert SQLx version owns two SQL statements, transfers root IDs, binds the
array, and must keep both stages semantically aligned. TeaQL declares the root
and relation bounds once inside the graph request.

LOC is formatting-sensitive, and the SQLx benchmark returns aggregate tuples
while TeaQL hydrates entities. It should be read as maintenance surface, not as
a universal productivity score. A fuller hand-written implementation would
also need typed SQLx rows, graph assembly, authorization, tenant isolation,
loaded-state handling, and observability.

Performance is only half of the problem

An expert can—and in this benchmark did—write the fast SQLx plan. TeaQL's
advantage is not that manual optimization is impossible. It is that application
developers do not have to discover, implement, and repeatedly preserve it
themselves.

Every handcrafted optimization creates another enforcement point. The root
query may contain a tenant predicate while the child query accidentally omits
it. The same can happen to authorization scope, soft-delete/version policy,
privacy masking, or trace metadata. Such mistakes are especially easy when an
AI coding agent rewrites a query for performance: the output looks faster and
can still leak another tenant's children.

TeaQL keeps both stages inside the same governed execution model. This is part
of TeaQL Harness Engineering: reduce the space in which generated code can be
fast but semantically or operationally wrong.

What the benchmark proves—and what it does not

It proves that API semantics can give a runtime enough information to avoid a
large amount of unnecessary database work. It also shows why query-count rules
are incomplete: one elegant statement can do much more work than several
bounded statements.

It does not prove that:

TeaQL has an intrinsically faster PostgreSQL driver than SQLx;
every window query is slow;
multiple queries are always preferable;
these timings generalize to other hardware, datasets, indexes, or databases;
2,378× is a general TeaQL-versus-SQLx performance ratio.

The controlled result is narrower and more useful:

The obvious SQLx query ranked 2.7 million rows for a page containing 103
relations. Once the business bounds were applied before ranking, most of that
work disappeared.

Reproduce it

The public
TeaQL runtime benchmark repository
retains four related evidence packages:

B001: Rust TeaQL, Diesel, and SeaORM typed graph workloads;
B002: raw JDBC across PostgreSQL and DuckDB;
B003: Java TeaQL across PostgreSQL and DuckDB;
B004: natural and expert root-first SQLx plans with a correctness gate.

Each package records source, query shape, environment, warmups, measurements,
cardinalities, and checksums. B004 also contains an executable LOC counter.

The 2,378× headline is therefore reproducible, but deliberately narrow. The
broader TeaQL claim is about making the good plan declarative, typed, reusable,
and governed.

A Stable Rust Tool Facade for Humans and AI: 52 Utilities, Explicit Intent

Philip Z — Wed, 30 Sep 2026 15:14:12 +0000

Rust does not have a shortage of good crates.

There is uuid for identifiers, chrono for time, rust_decimal for exact
decimal arithmetic, serde_json for JSON, and reqwest for HTTP. The challenge
in application development is often not finding a capability. It is keeping a
team fluent in many unrelated APIs while preventing infrastructure details from
spreading through business code.

AI coding makes that problem more visible. A model may understand the operation
we want while mixing together method names from another language, another
version, or another crate. The generated code looks plausible, but the API does
not exist.

TeaQL Tool is our attempt to make
that surface smaller and more predictable. It places 52 common utilities behind
one T::xxx() facade, separates lightweight and dependency-heavy features, and
adds an optional context layer that requires code to state why a value is being
read, calculated, or changed.

It is partly inspired by libraries such as Hutool, but the interesting question
is not how many helpers we can collect. It is whether a stable, narrow API can
serve both application developers and coding agents without hiding Rust's
underlying ecosystem.

The problem is API variance, not missing capability

A typical service quickly needs identifiers, timestamps, money, JSON, regular
expressions, encoding, files, hashing, and HTTP. Using each underlying crate
directly is entirely reasonable, especially when an application needs its full
feature set.

For repeated business operations, however, every dependency introduces another
construction pattern, error model, naming convention, and upgrade path. The
business layer gradually learns more infrastructure than business semantics.
An AI agent has an even larger API space in which to guess.

TeaQL Tool does not reimplement the ecosystem. It provides a small facade over
selected, mature crates:

use teaql_tool::T;

let id = T::id().uuid();
let now = T::time().now();
let value = T::json().parse(r#"{"name":"TeaQL"}"#)?;
let digest = T::hash().sha256(b"hello");

The caller starts at T, chooses a semantically named tool, and uses a compact
operation set. The facade can evolve its implementation without requiring every
call site to know which crate performs the work.

How the 52 tools are divided

The workspace contains five crates:

teaql-tool-core
       │
       ├── teaql-tool-std       26 standard tools
       ├── teaql-tool-extra     26 extension tools
       │
       └── teaql-tool           unified T:: facade
                    │
                    └── teaql-tool-context
                        UserContext and intent adapters

teaql-tool-std contains 26 general-purpose tools: text, time, date ranges,
IDs, money, decimals, JSON, regex, encoding, hashes, files, lists, maps,
validation, masking, emoji, networking, colors, units, trees, and related
operations.

teaql-tool-extra contains 26 tools with heavier dependencies or more explicit
IO: HTTP, commands, archives, Excel, CSV, images, email, JWT, encryption,
barcodes, QR codes, templates, an embedded key-value store, caching, a static
file server, a reverse proxy, cron scheduling, and file watching.

teaql-tool is intentionally thin. It owns the public facade and feature
selection. The default minimal feature enables the standard tools; applications
opt into extra when they need the heavier integrations.

Until the crates are published independently, the facade can be used from the
Git repository:

[dependencies]
teaql-tool = {
    git = "https://github.com/teaql/teaql-rust-utils",
    features = ["std", "extra"]
}

The project README
contains the complete inventory and the current context coverage.

Why use a facade in Rust?

A facade has a straightforward benefit: discoverability.

let tomorrow = T::time().add_days(T::time().now(), 1);
let encoded = T::codec().base64_encode(b"Hello");
let masked = T::desensitize().chinese_phone("13812345678");

Developers and agents can search one namespace instead of rediscovering a
dependency for every common operation. Naming can remain consistent across
categories, and an underlying dependency upgrade does not automatically become
an application-wide migration.

The same abstraction has a cost. A facade exposes a deliberately smaller API
than its dependencies. If an application needs detailed reqwest connection
pool control, the complete chrono type system, or advanced image encoding
parameters, it should use those crates directly. TeaQL Tool is a business
convenience layer, not a replacement for the Rust ecosystem.

Put the reason for an operation in the type flow

A predictable method name reduces API guessing. It does not explain why
application code is reading a file, obtaining the current time, or starting a
command.

teaql-tool-context explores a second idea: context-bound tools return wrappers
that require the caller to add intent before extracting a value or executing a
side effect.

The API distinguishes three meanings:

comment(...) explains a calculation;
purpose(...) explains a read;
audit_as(...) describes and executes a side effect.

For example:

use teaql_tool_context::prelude::*;

let now = ctx.time()
    .now()
    .comment("read the current time for the payment policy");

let deadline = ctx.time()
    .add_days(now, 7)
    .comment("calculate the payment grace period");

ctx.file()
    .write_string("deadline.txt", deadline.to_rfc3339())
    .audit_as("export the calculated payment deadline")?;

Calculation and read wrappers keep their inner values private. Code that needs
the value must explicitly consume the wrapper through the matching intent
method.

Side effects need a stronger boundary. MustAuditAs<T> stores a deferred action
rather than an already-computed result:

pub struct MustAuditAs<T> {
    action: Option<Box<dyn FnOnce(String) -> T + Send + 'static>>,
}

impl<T> MustAuditAs<T> {
    pub fn audit_as(mut self, description: impl Into<String>) -> T {
        let action = self.action.take().expect("action executes once");
        action(description.into())
    }
}

If a caller drops this value without calling .audit_as(...), the deferred file
write, command, or email is not performed. Tests cover both paths: execution
after an audit description and no execution after the pending action is dropped.

These wrappers enforce that intent is supplied at the API boundary. How that
description enters structured logs, traces, or an audit store remains an
application-runtime integration concern. Separating those responsibilities
keeps the type-level contract honest: collect intent first, route it through the
appropriate runtime policy second.

Why a smaller API helps coding agents

An LLM can know that a capability exists while still confusing its crate,
version, or exact method name. A facade narrows that generation space:

entry points follow T::xxx() or ctx.xxx();
related capabilities use a consistent naming style;
underlying dependency changes need not propagate into business code;
wrapper types let the compiler identify missing intent;
project rules can disallow bypassing context-bound IO in application code.

This does not eliminate hallucinations. It changes the problem from guessing
among many third-party APIs to selecting from a finite, project-owned surface,
then lets the Rust compiler verify the result.

For us, this is part of a broader harness-engineering principle: if a coding
rule matters repeatedly, move as much of it as possible from prompt prose into
an executable interface.

Current boundaries

TeaQL Tool is an early project, and several boundaries are intentional or still
in progress:

The facade covers frequent operations, not every capability of every wrapped crate.
Enabling extra adds networking, image, spreadsheet, SMTP, and server dependencies; compile time and binary size should be measured rather than ignored.
Stable facade names create a compatibility responsibility for maintainers.
The context layer currently covers all 26 standard tools, 21 extension tools, and a separate asynchronous HTTP adapter. Cron, proxy, server, and watcher adapters remain to be added.
Intent wrappers are an enforcement boundary, but full audit-sink integration is still runtime-specific work.

The next steps are compatibility and compile-fail tests, feature-level build
measurements, remaining context adapters, and deeper TeaQL runtime audit and
trace integration.

A question for the Rust community

Rust's crate ecosystem is strongest when applications can use focused libraries
directly. At the same time, business systems and coding agents benefit from
small, stable, project-owned interfaces.

Where should that boundary sit?

Does a Hutool-style facade reduce accidental complexity in a Rust application,
or does it hide crate boundaries that should remain explicit? For AI-generated
code, is a stable, constrained API more valuable than direct access to every
underlying capability?

TeaQL Tool is open source, and we would value concrete criticism of both the
tool selection and the intent-wrapper design:

github.com/teaql/teaql-rust-utils

Expanding the TeaQL Ecosystem: Seamless Integration with Axum Web and Redis Distributed Cache

Philip Z — Sun, 02 Aug 2026 13:30:00 +0000

As the core architecture of TeaQL continues to mature, we are excited to announce two heavy-weight extension modules to the TeaQL ecosystem: the Web Module (teaql-web-integration-axum) and the Red Module (teaql-cache-integration-redis).

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.

The Return of E Expressions: Fluent Chaining and Structured Panics for AI Auto-Healing

Philip Z — Sat, 01 Aug 2026 13:30:00 +0000

In the evolution of TeaQL, we've constantly navigated the tension between developer ergonomics and idiomatic Rust. Recently, we made a bold decision: we are bringing back the beloved E:: fluent expression chain to Rust.

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:

Human Ergonomics: Developers get the "mental candy" of fluent .get_foo().get_bar() chaining.
Performance: Zero allocations, purely reference-driven.
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.

Kernel-Level Audit & Privacy: Building Resilient Audit Chains in the AI Coding Era

Philip Z — Fri, 31 Jul 2026 13:30:00 +0000

In the era of AI Coding, business code may be co-generated and modified by human developers, AI agents, or automated tools.
This brings a new challenge:

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:

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.
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:

RawAuditEvent: Contains 100% complete mutation data and raw requests, restricted for internal low-level use only.
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:

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.
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":

Blocking Errors (Error): When core high-risk privacy fields (like password, token, or ssn) are detected without masking, the engine blocks code generation.
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\" />"
   }

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.

TeaQL Java Runtime: Modular Refactor, Multi-Framework Ready, Rust-Aligned

Philip Z — Fri, 31 Jul 2026 13:30:00 +0000

We refactored the TeaQL Java runtime (teaql-java) to achieve three goals:

JPMS module boundaries — seal internal packages, expose only what generated code needs
Spring Boot independence — run without Spring Boot using a plain main() function
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

Feature	Rust	Java
Module boundaries	Cargo workspace	JPMS `module-info.java`
Query enforcement	Compile-time (ownership)	`ExecutableRequest` + `purpose()`
`RequestPolicy`	`RequestPolicy` trait	`RequestPolicy` interface
Audit masking	`audit_mask_fields` per entity	Same, via `EntityDescriptor`
SQL log	`LogManager` + env vars	Same
App sinks	`SafeAuditEventSink`	`AuditEventSink` + `LogSink`
Non-Boot runtime	Native	`TQLResolver` + `SimpleResolver`
Android-style portable SQL	N/A	`teaql-sql-portable` + `TeaQLDatabase`
Quarkus support	N/A	`teaql-quarkus` + CDI Producer
Micronaut support	N/A	`teaql-micronaut` + Bean Factory
DB abstraction	`TeaQLDatabase` trait	`TeaQLDatabase` interface

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.

Enforcing Request Policy at the Runtime Boundary

Philip Z — Thu, 30 Jul 2026 13:30:00 +0000

In a multi-tenant business system, the dangerous query is often not obviously
dangerous.

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(())
    }
}

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.

TeaQL Showcase: See What Your Business Code Actually Does

Philip Z — Wed, 29 Jul 2026 12:00:00 +0000

Instead of hiding database behavior behind an opaque ORM, this demo shows the full execution path of a domain action:

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);

Input	JSON	Generated SQL
No search	`{}`	`SELECT ... FROM task_data WHERE (version > 0)`
`calibrate`	`{"name": "calibrate"}`	`SELECT ... FROM task_data WHERE (version > 0) AND (name LIKE '%calibrate%')`

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

#	TeaQL API	App Feature	Command
1	`ensure_rusqlite_schema_for`	Auto-create tables & seed data	Startup
2	`filter_with_json`	Dynamic search / wildcard load	`/s`
3	`facet_by_status_as`	Status count aggregation	Board reload
4	`Q::tasks().comment("Create tasks").new_entity()`	Create task with defaults	`<name>`
5	`RusqliteIdSpaceGenerator`	Unique ID generation	`<name>`
6	`Extension Traits`	Domain Behavior Injection (DDD)	`/mv`, `/del`
7	`.return_type::<T>()`	Custom partial projection & stats DTOs	Optimization
8	`EntityStatus::UpdatedDeleted`	Audited soft-delete with concurrency	`/del`
9	`.comment()`	Query intent tracing	All queries
10	`EntityEventSink`	Field-level lifecycle diffs & Audit	All mutations

📐 Architecture

3-Layer Separation

Layer	File	Responsibility
UI / Presentation	`ui.rs`, `startup.rs`, `tui.rs`	Ratatui layout, startup animation, log syntax highlighting, terminal management
Application Layer	`main.rs`, `app.rs`, `commands.rs`	App state, command parsing, event loop orchestration
Service & Domain	`service.rs`, `logging.rs`, `models.rs`	TeaQL queries, DDD aggregate roots, audit sinks, view models

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:

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.
Translation Service: A dedicated background service takes this model and translates it into a dense, strictly-typed Rust API layer.
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.

Command	Shortcut	Description	Example
`<name>` / `/add <name>`	—	Create a new task in Planned status	`calibrate sensor` or `/add calibrate`
`/move <id> [status]`	`/mv`	Transition task status (planned/ready/executing/verified; default: next)	`/move 3` or `/mv 3 ready`
`/search <keyword>`	`/s`	Filter tasks by keyword (empty to clear)	`/search calibrate` or `/s`
`/delete <id>`	`/del`	Permanently delete a task	`/delete 3`
`/exit` / `/quit`	`/q`	Quit the application	`/exit`
—	`ESC`	Immediate exit	—
—	`Up/Dn`	Scroll Action Logs viewport	—

⚙️ 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!)

DEV Community: Philip Z

Stop Giving Your AI Agent Raw SQL

The missing layer beneath an agent SDK

Deny by absence

The model never receives UserContext

Approval and authorization solve different problems

Preserve the persisted result

Observe failures without leaking them

Native Vercel AI SDK integration

Run the demonstration without an API key

Start with TypeScript, preserve cross-runtime semantics

What is available today

Try it and challenge the boundary

TeaQL Was 2,000x Faster Than the Obvious SQLx Query—Here’s What Actually Happened

What TeaQL is

The obvious single-statement SQLx solution

The business request carried a stronger bound

The SQLx control explains the result

How much code did each plan require?

Performance is only half of the problem

What the benchmark proves—and what it does not

Reproduce it

A Stable Rust Tool Facade for Humans and AI: 52 Utilities, Explicit Intent

The problem is API variance, not missing capability

How the 52 tools are divided

Why use a facade in Rust?

Put the reason for an operation in the type flow

Why a smaller API helps coding agents

Current boundaries

A question for the Rust community

Expanding the TeaQL Ecosystem: Seamless Integration with Axum Web and Redis Distributed Cache

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

Feature 1: TeaContext Extractor

Feature 2: Fully Compatible WebResponse

Feature 3: Native Support for Facets (Aggregated Categorization)

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

Summary: Moving Toward the Ultimate Agentic State

The Return of E Expressions: Fluent Chaining and Structured Panics for AI Auto-Healing

The Ping-Pong of API Design

Bringing Back E:: (The Right Way)

Strict Panics: Rust's Bottom Line

Designing for AI: The Structured Panic

The Magic of <broken>

Conclusion

Kernel-Level Audit & Privacy: Building Resilient Audit Chains in the AI Coding Era

1. Kernel-Level Auditing to Prevent Mistakes Automatically

Dual-Channel Design: Isolating Internal Auditing from Custom Hooks

2. The Evolution from RawAuditEvent to SafeAuditEvent

Metadata-Based Automatic Masking and Truncation

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

Conclusion

TeaQL Java Runtime: Modular Refactor, Multi-Framework Ready, Rust-Aligned

Why Refactor?

Architecture: Three Layers

JPMS Module Boundaries

Spring Boot Independence

Compile-Time Query Enforcement

RequestPolicy (Rust Alignment)

Dual-Layer Audit & Logging

Layer 1: Runtime (Environment Variables, No Code)

Layer 2: App Layer (Customizable, Masked)

Masking (Aligned with Rust)

Multi-Framework Support via TeaQLDatabase

Android

Quarkus (CDI integration)

Micronaut (Bean Factory integration)

Plain Java (no framework)

Summary Table

Enforcing Request Policy at the Runtime Boundary

The Multi Talent Problem

The Wrong Place for the Rule

The Runtime Boundary

A Multi Talent Policy

Protecting More Than Rows

Why UserContext Is the Right Place

Auditing Sensitive Reads

The Design Principle

TeaQL Showcase: See What Your Business Code Actually Does

TeaQL for Rust

📁 Project Structure

The model never receives `UserContext`

Bringing Back `E::` (The Right Way)

The Magic of `<broken>`

Scenario 1: Schema Bootstrap (`ensure_rusqlite_schema_for`)

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

Scenario 3: Faceted Aggregation (`facet_by_status_as`)

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

Scenario 5: ID Space Generation (`RusqliteIdSpaceGenerator`)

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

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

Scenario 10: Entity Audit Subsystem (`EntityEventSink`)