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:

1. The facade covers frequent operations, not every capability of every wrapped crate.
2. Enabling extra adds networking, image, spreadsheet, SMTP, and server dependencies; compile time and binary size should be measured rather than ignored.
3. Stable facade names create a compatibility responsibility for maintainers.
4. 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.
5. 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

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.

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(&context)
    .await?;

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

1. choose 100 matching roots;
2. load no more than ten ordered relations for each selected root;
3. hydrate only the referenced Link, LinkType, and Work objects;
4. 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:

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

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

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.

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:

1. B001: Rust TeaQL, Diesel, and SeaORM typed graph workloads;
2. B002: raw JDBC across PostgreSQL and DuckDB;
3. B003: Java TeaQL across PostgreSQL and DuckDB;
4. 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.

The two ideas can produce a similar developer experience: a frontend composes a query instead of waiting for a backend team to add one more endpoint. But they place the public boundary at different layers of the system.

Supabase reflects a PostgreSQL schema into an API. TeaQL exposes capabilities from a shared business model and lets a trusted runtime decide how those capabilities are executed. That difference becomes important when an application has complex authorization, several backend languages, multiple data sources, or AI agents that need composition without database authority.

First, Supabase solves a real problem well​

Supabase's official documentation describes its Data API as an API generated directly from the database schema. It can be called from a browser, uses PostgREST, and works with PostgreSQL grants and Row Level Security. Supabase supports both a two-tier architecture, where the browser accesses the Data API, and a three-tier architecture with an application server.

That is a compelling model for many products:

const {data, error} = await supabase
  .from('orders')
  .select('id,status,total_amount')
  .eq('status', 'NEW')
  .order('id', {ascending: false})
  .limit(20)

The application gets a useful query surface quickly. PostgreSQL remains the execution engine, while grants and RLS determine which objects and rows a role may access. Supabase explicitly recommends RLS and least-privilege grants for frontend access and warns that service-role credentials must never be exposed in the browser.

Those are strengths, not shortcomings. TeaQL is not trying to reproduce a PostgreSQL platform, authentication product, storage service, or hosted backend. It starts from a different question:

What should the query boundary look like when the public contract is the business model rather than the database schema?

Similar experience, different authority​

A TeaQL TypeScript application normally composes the query through the model-generated Q API:

const orders: SmartList<CustomerOrder> = await Q.customerOrders()
  .withOrderNumberStartingWith('WEB-')
  .withTotalAmountGreaterThanOrEqualTo(1000)
  .selectOrderNumber()
  .selectTotalAmount()
  .orderByIdDescending()
  .limit(20)
  .comment('what: load high-value active orders')
  .purpose('why: render the operations queue')
  .executeForList(context)

customerOrders, withOrderNumberStartingWith, selectTotalAmount, and the returned CustomerOrder are generated from the model. They are not strings invented by the application. Rename or remove a modeled field and this code stops compiling. Editor completion also exposes only the operations generated for that field type.

The generated request builds TeaQL's internal typed query model. At a federal boundary it is serialized into a canonical TeaQL Federal Protocol request; the application does not need to construct that string-keyed wire envelope itself. The browser transmits neither SQL nor a runtime-native object. The receiving application maps the public entity and field vocabulary to capabilities that its trusted policy permits.

TypeScript query
      │
      ▼
TeaQL Federal Protocol
      │
      ▼
entity / field / operator / limit policy
      │
      ▼
tenant + actor + purpose context
      │
      ▼
Java or Rust TeaQL runtime
      │
      ▼
configured data services

The same TypeScript query can be executed by a Java backend or a Rust backend. The backend may use PostgreSQL, SQLite, another supported provider, or a composed data-service topology. The frontend contract does not become a raw view of any one physical schema.

A business model is not just a nicer table name​

Database tables are an implementation model. A governed application needs additional concepts:

• which entities and fields this caller may query;
• which operators are allowed for each exposed field;
• tenant and regional boundaries injected by the server;
• required query limits and stable ordering;
• loaded, null, and not-loaded object state;
• comments describing what the query does;
• purpose describing why it is being executed;
• audit and telemetry that remain independent from business payloads;
• consistent semantics when a service moves between runtime languages.

Some of these rules can be implemented with PostgreSQL RLS, views, functions, grants, and API-server code. TeaQL's proposition is not that they are impossible elsewhere. It is that they should form one generated, testable runtime contract rather than being reconstructed independently in every application layer.

This is especially relevant to AI agents. An agent can productively combine approved predicates, projections, relations, and facets. It should not receive the authority to invent SQL against an internal schema or to omit the tenant condition because it did not appear in the prompt.

One model generates both sides; only the trusted side owns policy​

TeaQL starts with one KSML business model. From that model, the generator can produce both sides of the interaction:

                         one KSML model
                               │
                ┌──────────────┴──────────────┐
                ▼                             ▼
       generated client API          generated server runtime
       Q.customerOrders()             entities and metadata
       typed predicates               query execution
       typed projections              checker and fix lifecycle
       typed result objects           mutation and audit lifecycle
                │                             │
                │                    application customization
                │                    tenant and actor policy
                │                    workflow authorization
                └──────── TFP ────────────────┘

The client is intentionally close to the generated model. A frontend developer normally consumes the generated Q API directly. The client does not need a copy of the organization's authorization implementation, and it must not receive server secrets or trusted policy state.

The server is generated from the same model but is designed to be customized. An application installs its runtime module, checkers, fixes, behaviors, trusted field mappings, and authorization rules there. The server may expose only a subset of the generated model through TFP. It may also add tenant conditions or reject an operation even when the client constructed a perfectly valid typed query.

This separation is important: type-safe means structurally valid; it does not mean authorized. Generated client code prevents accidental field and operator mistakes. The trusted server decides whether this actor may perform this query or mutation in the current business context.

Because both sides originate from the same model, they share entity, field, relationship, nullability, and query semantics without sharing authority. The client can remain mostly generated and immediately usable, while the server can be deeply adapted to the organization.

Tenant isolation is only the beginning​

Consider a procurement application used by many companies. Every contract belongs to a tenant. A user from tenant A must never read or mutate a contract from tenant B—even if a request explicitly supplies tenant B's identifier.

TeaQL treats the tenant as trusted context rather than ordinary client input:

browser request: contracts over 1,000,000
authenticated context: tenant=A, actor=alice, roles=[buyer]

effective server query:
  requested business predicates
  AND tenant = context.tenant
  AND fields/operators allowed by server policy
  AND runtime execution limits

The frontend can compose the useful part of the question, but it cannot remove or replace the server-injected tenant boundary. The same rule applies whether the query is executed by the Java runtime today or a Rust service after a later migration.

Now add a common enterprise authorization rule:

A contract up to 1,000,000 may follow the normal approval path. A contract above 1,000,000 must be approved by a second authorized person, and the second approver cannot be the person who submitted it.

This is not merely “can this role update this row?” The decision depends on:

• the tenant of the contract and the actor;
• the contract amount and currency;
• the current workflow state;
• the actor's approval authority;
• prior mutation history;
• separation of duties between submitter and approver;
• possibly regional or legal-entity rules.

In TeaQL, the generated mutation enters the server runtime with an authenticated context. Server-side checker/behavior policy can reject the transition, or move the contract into a PENDING_SECOND_APPROVAL state and record the decision in the mutation and audit lifecycle. The client still uses the generated contract API; it does not duplicate the threshold rule or decide that its own request is authorized.

PostgreSQL and Supabase can implement sophisticated rules using RLS, grants, views, triggers, database functions, or a custom application server. The point is not that a million-unit approval is impossible there. The architectural question is where that evolving business workflow lives. Once an application needs value-dependent approval, separation of duties, audit reasons, several services, and multiple runtime languages, a table-reflected API alone is no longer the complete business boundary.

TeaQL keeps the public query composable while placing these decisions in a model-aware server runtime. That is what “governed” adds to “direct.”

Facets show why this boundary matters​

Suppose an order page needs both filtered orders and status counts. The client can request a relation facet:

const statusValues = Q.orderStatuses()
  .selectCode()
  .selectLabel()
  .countAs('orderCount')
  .comment('what: load status facet values')
  .purpose('why: render order filters')

const orders = await Q.customerOrders()
  .withTotalAmountGreaterThanOrEqualTo(1000)
  .selectOrderNumber()
  .limit(20)
  .comment('what: load orders with their status facet')
  .purpose('why: render the governed order list')
  .facetByStatusAs('statusFacet', statusValues, true)
  .executeForList(context)

const statusFacet = orders.facet('statusFacet')

The server retains the outer filter when calculating membership counts. It validates the relation, nested fields, aggregate, page limit, comment, and purpose. It can return every allowed status—including a zero-count value—or only matched values according to the explicit option.

This is still composable frontend querying, but the expensive operation is not defined solely by whatever expression arrives from the browser. Its shape is a bounded protocol capability.

TeaQL currently retains executable conformance for this path with a TypeScript client against both Java and Rust endpoints. The same fixture verifies the result and negative policy cases instead of treating a successful HTTP response as sufficient evidence.

Where each approach fits​

The useful comparison is not “which product has more features?” It is “where should authority live for this application?”

For a small PostgreSQL application that wants a backend immediately, a direct Data API may be exactly the right abstraction. For a domain with substantial business policy, several runtimes, gradual Java-to-Rust migration, or agentic query composition, binding the public query contract directly to storage can become limiting.

The goal is not unrestricted frontend querying​

“Let the frontend query” can sound like moving backend authority into the browser. That is not the TeaQL design.

The client controls composition only within a capability vocabulary. The server owns identity, tenant scope, allowed entities, field mappings, operators, limits, execution, and error classification. Unknown fields and unsupported operators fail closed. Internal database errors and mappings do not become the public protocol.

That produces a useful middle ground:

fixed endpoints            governed composition                raw SQL
low flexibility   <------------------------------------>   high authority
                         TeaQL aims here

Applications and agents gain enough freedom to answer questions that were not pre-packaged as dedicated endpoints. The backend keeps enough authority to make those questions safe, explainable, portable, and testable.

One sentence to remember​

Supabase gives applications a direct Data API. TeaQL gives applications and AI agents a governed business query API.

They address neighboring needs. The distinction is the layer being exposed: the database as an API, or the governed business model as an API.

Further reading:

• Supabase Data REST API
• Supabase: securing the Data API
• TeaQL on GitHub

It preserves loaded, null, and not-loaded state. It builds an identity-consistent object graph. It carries query purpose and diagnostic comments. The same runtime also supports checker/fix behavior, mutation ledgers, audit boundaries, and cross-data-source relations.

That raises a fair question: what does this additional runtime model cost on a real relational graph?

We tested a retained TeaQL Rust build against Diesel and SeaORM using a PostgreSQL copy of the public MusicBrainz database. The result is more useful than a simple winner: across three relationship shapes, TeaQL consistently landed between Diesel and SeaORM—and came within 3.4% of Diesel on one five-query graph.

The result first​

These are medians from the retained local run on August 25, 2026:

Every framework passed the same cardinality and checksum gate before its timing was accepted. A fast result with a missing relation, projection, active-version predicate, or duplicate path was a failed run, not a benchmark result.

This is not evidence that TeaQL is universally faster than SeaORM, or that Diesel is universally faster than TeaQL. It is evidence that TeaQL's generated, identity-preserving relationship loading is competitive on these three graph shapes while retaining a broader runtime contract.

Three graph shapes, not one convenient query​

A single benchmark can accidentally select the exact shape one implementation optimizes best. We therefore retained three materially different reads.

MB01: a deep release graph​

MB01 follows seven entity types:

Release
  -> Medium
  -> Track
  -> Recording
  -> ArtistCredit
  -> ArtistCreditName
  -> Artist

Each operation returns:

• 10 releases;
• 14 media;
• 133 tracks;
• 176 artist-credit-name path traversals;
• 176 artist traversals;
• checksum 13,877,887,930.

All three implementations execute seven parameterized statements and project the same IDs, versions, names, and foreign keys. This workload tests depth and repeated identities more than raw row volume.

TeaQL's application query is assembled from generated, typed request pieces. For example, the reusable lower half of the graph can be named once:

fn artist_credit_graph() -> ArtistCreditRequest {
    Q::artist_credits_minimal()
        .select_name()
        .select_artist_credit_name_list_with(
            Q::artist_credit_names_minimal()
                .select_name()
                .select_artist_with(Q::artists_minimal().select_name()),
        )
}

fn recording_graph() -> RecordingRequest {
    Q::recordings_minimal()
        .select_name()
        .select_artist_credit_with(artist_credit_graph())
}

fn medium_graph() -> MediumRequest {
    Q::mediums_minimal()
        .select_name()
        .select_track_list_with(
            Q::tracks_minimal()
                .select_name()
                .select_recording_with(recording_graph()),
        )
}

Q::releases_minimal()
    .select_name()
    .select_medium_list_with(medium_graph())
    .order_by_id_desc()
    .limit(10)
    .comment("what: repeatedly load the MB01 release graph")
    .purpose("why: compare mainstream ORM graph loading")
    .execute_for_list(&context)
    .await?;

The helper functions are ordinary typed request builders: they can be reused, extended, or nested in another request without falling back to SQL strings or an untyped include specification. This makes a large query read more like a set of Lego pieces than one monolithic expression. comment and purpose remain on the final execution boundary because they describe this concrete operation, not a reusable projection fragment.

The composed request is expanded into one query per graph level. The runtime installs the results into a flat identity graph and exposes typed relationships without requiring application-owned lookup maps.

MB02: a wide collaboration graph​

MB02 selects the 100 ArtistCredit rows with the largest artist_count above one, loads their ordered ArtistCreditName members, and resolves every typed Artist.

Each accepted operation returns:

• 100 artist credits;
• 2,090 memberships;
• 2,090 resolved artists;
• zero artist_count mismatches;
• checksum 2,584,441,647.

This graph executes only three queries, but materializes 2,290 identity-bearing entities across 2,090 relation paths. Here TeaQL was 15.3% behind Diesel and 10.8% ahead of SeaORM. The result suggests that TeaQL's graph assembly scales reasonably as decoding and relationship volume dominate fixed runtime costs.

MB03: a small generic link graph​

MusicBrainz represents recording-to-work relationships through a generic link model. MB03 selects 100 recent recordings that have work relations, loads up to ten association rows per recording, and resolves both sides:

Recording
  -> LRecordingWork
       -> Link -> LinkType
       -> Work

The accepted result contains 103 association rows, 103 links, 103 link types, and 103 works. No parent exceeds the per-parent limit, and the checksum is 6,601,766,716.

This workload performs five database queries for only 512 total entities. It is therefore sensitive to fixed query, repository, and graph-assembly costs. In the retained run, TeaQL was only 3.4% behind Diesel and 27.2% ahead of SeaORM.

What “mainstream usage” means here​

We did not ask every framework to imitate TeaQL's internal strategy or race on hand-written SQL.

• Diesel uses derived Associations, belonging_to, and grouped_by, plus typed eq_any parent lookups where the traversal direction requires them.
• SeaORM uses LoaderTrait::load_many, LoaderTrait::load_one, and its typed query API.
• TeaQL uses its generated Q API and nested select_*_with relation selection.

No implementation uses raw SQL, stored procedures, custom PostgreSQL functions, or a workload-specific result cache. A single join across the whole graph was deliberately excluded because multiple to-many edges multiply rows and do not represent a robust default loading strategy.

The database sees different parameterization details where each framework has its own normal policy. TeaQL uses scalar equality for one ID, scalar IN for small sets, and PostgreSQL = ANY($1) for larger sets. That stable array-bound shape avoids expanded-parameter limits; it is not presented as proof of a universal speed advantage.

Measurement protocol​

The retained comparison used:

• local PostgreSQL with the same MusicBrainz dataset for all frameworks;
• Rust --release builds;
• sequential operations with no client-side concurrency;
• connection and runtime construction outside the measured interval;
• three complete warm-up operations per framework process;
• five framework-order-rotated rounds;
• 100 complete operations per MB01 result;
• 20 complete MB02 and MB03 operations per result;
• SQL and process logging disabled for all measured frameworks;
• full graph traversal and checksum validation in every process.

We report medians because the machine showed material round-to-round variance. Publishing extra decimal places would imply accuracy the experiment does not have.

Reproducing the evidence is intentionally simple​

The complete B001 evidence package is public in teaql/teaql-runtime-benchmark. There are two useful levels of reproduction.

First, anyone can recalculate all nine published medians and verify the raw logs, correctness gates, model, runner sources, schema augmentation, and every file in the retained generated library with one command:

git clone https://github.com/teaql/teaql-runtime-benchmark.git
cd teaql-runtime-benchmark
benchmarks/B001-rust-orm-musicbrainz/scripts/verify.sh

This audit needs no database and no Rust compiler. The same command runs in the repository's GitHub Actions workflow.

Second, the exact 2026-08-01 MusicBrainz sample can be reconstructed with a fixed snapshot URL, SHA-256, and pinned official loader commit:

benchmarks/B001-rust-orm-musicbrainz/scripts/setup-dataset.sh
export MUSICBRAINZ_BENCHMARK_DATABASE_URL=\
'postgresql://musicbrainz:musicbrainz@127.0.0.1:55434/musicbrainz_teaql'
benchmarks/B001-rust-orm-musicbrainz/scripts/preflight.sh

The setup downloads the public sample, verifies it, imports the official schema, creates a separate TeaQL benchmark database, applies the idempotent augmentation, and checks the fixture cardinalities. It requires Docker Compose, about 4 GiB of RAM, and roughly 15 GiB of disk.

There is one important boundary. A 2026-09-02 audit found that the retained generated library uses the older EntityRoot API and does not compile with the runtime commit recorded as 4.2.25; the original runner lock file was also not retained. We therefore classify this as historical evidence whose numbers are auditable, not an exact source-and-latency replay. We do not silently switch runtime versions to make the command green. A new evidence run will add the fully locked end-to-end replay while preserving this historical result.

Two more TeaQL workloads, without an ORM ranking​

We also reran two exploratory TeaQL-only scenarios after moving reverse relations out of generated entity storage:

We have not yet implemented equivalent mainstream Diesel and SeaORM versions of MB04 and MB05. These numbers are useful runtime regression evidence, but they are not a cross-framework comparison.

That distinction matters. A benchmark becomes less credible every time an author quietly converts “not measured” into “probably faster.”

Why relations moved out of Rust entity structs​

The relation-state design being evaluated changes how generated reverse relations are represented. A parent entity no longer embeds every reverse SmartList<Child> in its structure. Instead, the runtime owns the loaded identity graph, and generated accessors return a RelationHandle with three explicit states:

Loaded     the selected relationship contains values
Empty      the relationship was selected and contains no values
NotLoaded  the relationship was not selected

There is no implicit database access when an accessor is called.

This reduces generated type-graph growth and makes cyclic models easier for Rust to compile and represent. It also keeps the public API compact: business code still asks the entity for its typed relation, while the data lives in the runtime identity graph.

The trade-off is measurable. Direct traversal through a relation handle is slightly more expensive than reading an embedded list. In MB01, traversal was roughly 0.144 ms in this run versus about 0.062 ms in an earlier retained baseline. The absolute difference is small compared with database and hydration time, but we report it because removing an embedded field is not literally free.

Overall MB01–MB05 query performance did not regress as a group, and all correctness gates remained stable. We do not attribute every improvement to RelationHandle; the measured build also contains compact-row decoding, prepared-statement caching, reduced metadata allocation, and flatter identity hydration introduced during the same optimization period.

Performance is not the whole runtime contract​

Diesel is an excellent reference point for efficient, strongly typed Rust database access. SeaORM provides a productive async ORM model with generated entities and relationship loaders. TeaQL targets a different application boundary: one governed domain model generates consistent APIs across Java, Rust, TypeScript, Swift, Python, .NET, and Go.

The measured TeaQL query path additionally preserves:

• typed loaded/null/not-loaded semantics;
• identity-consistent relationship graphs;
• mandatory query purpose and diagnostic comments;
• active-version filtering;
• a shared contract with checker/fix, audit, and mutation APIs;
• runtime-managed cross-data-source relationship capability.

A query log that records intent, not only SQL​

The two strings at the end of the benchmark request are not decorative:

.comment("what: repeatedly load the MB01 release graph")
.purpose("why: compare mainstream ORM graph loading")

TeaQL carries both into query diagnostics. The SQL tells an operator what the database executed; comment identifies the concrete operation, while purpose records why the application asked for it. That distinction is useful when a slow query, an unexpected access path, or AI-generated application code must be reviewed after the fact. It also gives observability systems a stable piece of business intent instead of asking an operator to reconstruct intent from a prepared statement and a stack trace.

There is a small discipline cost: application queries must declare their intent. We consider that a feature of a governed runtime, especially when more code is produced or modified by AI agents.

The benchmark is part of a harness, not a one-off race​

TeaQL is developed with the TeaQL Agent Kit, a Harness Engineering workflow that gives coding agents model rules, generated Assist material, executable checks, and retained evidence. The goal is not merely to make an agent produce a query that compiles once. The harness repeatedly checks whether model evaluation, generation, runtime behavior, and documentation still agree as the system evolves.

The same domain model and API concepts are maintained across seven generated runtime families: Java, Rust, TypeScript, Swift, Python, .NET, and Go. Each language keeps its native naming and type-system conventions, while TeaQL's Q, E, mutation, checker/fix, audit, loaded-state, and Assist vocabulary provide a shared conceptual contract. Conformance evidence matters here: “seven languages” is an engineering obligation to detect and close gaps, not a claim that every implementation already has identical maturity or performance.

Not every one of those capabilities is exercised by these read-only queries, so the benchmark cannot assign a precise cost to each feature. They explain why our goal is not to turn TeaQL into a thin SQL tuple decoder. The engineering target is to keep the governed runtime close enough to the fastest mainstream typed approach that teams do not have to abandon the higher-level contract for ordinary application queries.

On this MusicBrainz sample, that target is credible: TeaQL is not the fastest in the table, but it is consistently competitive—and the gap is small enough to measure rather than hand-wave. The value proposition is therefore not “the fastest Rust query at any cost.” It is competitive query performance together with explainable intent, a continuously exercised AI coding harness, and one domain contract that can travel across seven languages.

TeaQL Rust is available at github.com/teaql/teaql-rs. The benchmark article and its follow-up evidence are tracked publicly in teaql-io-site issue #13.

Authorship disclosure: This article was written by Philip Zhang with LLM-assisted drafting and editing. The benchmark design, execution, validation, and conclusions were reviewed by the author.

Then we implemented the same programming model in Rust.

Rust did not let us casually hide shared mutable state behind an object graph. Ownership and borrowing forced us to answer questions that our other runtimes had allowed us to postpone.

• Who owns the pending changes?
• What is the mutation boundary when a parent and its children change together?
• How does a save operation discover a change made through another reference?
• Where is the original version kept for optimistic locking?
• What happens to pending changes when validation or persistence fails?

Our first reaction was that Rust made an otherwise ordinary API unnecessarily difficult. The more useful conclusion was the opposite: the ordinary API had been relying on behavior that was never clearly designed.

The answer became a mutation ledger shared by an object graph. It began as a way to make Rust mutation practical. It ended up becoming the mutation model for all seven TeaQL runtimes.

The Hidden Contract Behind a Setter​

Consider a loaded order with two lines. Business code changes the shipping address, changes the quantity of one line twice, and removes the other line. The final save needs more than the current memory representation.

It needs to know that:

• the order and both lines belong to one mutation unit;
• the quantity has one final pending value, not two database updates;
• the removed line is a deletion, not an object that happened to disappear;
• each existing entity must be updated against the version originally loaded;
• validation and automatic fixes must run before any database call;
• a failed save must not make the in-memory graph look committed.

A runtime can infer some of this from snapshots. It can place interceptors in setters or proxies around entities. It can keep a session-level identity map. But each mechanism creates an implicit contract, and those contracts are easy to implement differently in different languages.

Rust exposed that ambiguity early. We could not depend on a web of invisible aliases and later ask the runtime to reconstruct what had happened. We needed a single explicit owner for mutation state.

One Root, One Pending Ledger​

Every mutable entity in a working graph now owns or references the same EntityRoot. This is a technical root for pending mutation state, not a domain aggregate root and not a tenant or authorization context.

The language-neutral model is deliberately small:

EntityKey = (entityType, entityId)

EntityRoot
  changes: Map<EntityKey, Map<FieldName, NewValue>>
  originalVersions: Map<EntityKey, Version>
  newKeys: Set<EntityKey>
  deletedKeys: Set<EntityKey>

Generated update methods write into this root. If the same field is updated more than once before save, the entry is overwritten with the final value. The ledger records the state we intend to persist, so repeated writes are last-write-wins.

For example, the conceptual operation:

line.update_quantity(2);
line.update_quantity(3);

leaves one pending change for quantity = 3. It does not require two mutation commands and does not lose the fact that the field was deliberately changed.

When a parent and its children are loaded or assembled together, they adopt the same root. A change made through a child therefore belongs to the same ledger consumed when the graph is saved. The save receiver is merely an entry point; it is not the limit of mutation discovery.

This was the key move for Rust. Instead of trying to make every entity secretly observe every other entity, we made mutation state an explicit shared resource with a precise lifecycle.

Why the Ledger Stores New Values, but Not Old Values​

An audit record often needs both old and new values. It is tempting to copy both into the mutation ledger, but that would duplicate state and introduce another consistency problem.

A loaded entity already retains its original field state. The root records the final intended values and the versions seen during hydration. When audit evidence requires an old/new pair, it can combine the loaded state with the ledger.

This separation also makes the purpose of the root clearer. It is a record of pending intent, not a second complete copy of the entity graph.

There are limits to that choice. If an application discards the original loaded state, it cannot later reconstruct old values from the root alone. That is intentional: a lightweight in-memory mutation ledger should not pretend to be a durable history system.

Checker and Fix Are Part of the Same Mutation​

TeaQL applies two kinds of pre-persistence behavior. A checker rejects invalid state with a domain-facing error before the database sees it. A fix supplies context-derived values such as creation time, update time, or a required root reference.

Both operate on the pending mutation, not beside it.

That means a fix does not silently alter an entity through a special path. Its change is written to the same ledger as an application update. The eventual provider command, audit evidence, and diagnostic view all see the same final intent.

The ordering is important:

business updates
      |
      v
shared mutation ledger
      |
      v
checker and context-driven fix
      |
      v
audited save / provider commands
      |
      +--> success: adopt authoritative versions and clear committed entries
      |
      `--> failure: retain pending state

Database constraints remain a final safety boundary, but they should not be the first place an application learns that a required business field is missing. The ledger gives checker and fix logic a complete graph-wide view before the provider is called.

Failure Semantics Matter as Much as the Happy Path​

Dirty tracking designs often focus on detecting a change and generating an update. The difficult part is deciding what the in-memory state means after something goes wrong.

If checking rejects the mutation, no provider call should occur and the pending ledger should remain available for correction. If the provider fails, the runtime must not clear the ledger or claim that the new version was committed. On success, committed entries are cleared and authoritative state—especially generated identifiers and versions—is adopted.

These rules make failure observable and retry behavior understandable. They also create useful boundaries for future diagnostics. A system can distinguish:

• what business code intended to change;
• what checker or fix logic added;
• what command was submitted;
• whether the command committed or failed.

That is already valuable without turning the design into a permanent event log.

This Is Not Event Sourcing​

The word “ledger” can suggest event sourcing, but this design has a different job.

An event-sourced system normally persists an ordered sequence of domain events as its source of truth. Our mutation ledger is transient pending state. It may collapse multiple assignments to the same field into one final value, and it is cleared after a successful save. Durable audit records can be produced from it, but durability and replay are not properties of the ledger itself.

It also differs from conventional ORM dirty checking. Snapshot comparison asks, “What is different now?” The ledger records, “What does this graph intend to change?” The difference becomes important for deletions, optimistic versions, context-driven fixes, failure handling, and cross-entity operations.

Rust Was the Design Review​

There is a recurring lesson in cross-language framework work: a feature that is easy to hide in one language may still be poorly specified.

Garbage collection, reference semantics, dynamic interception, or framework proxies can make a convenient API possible without forcing its ownership model into the open. Rust removes many of those escape routes. That can feel like friction, but the friction is information. It tells us where the architecture depends on an unnamed owner, an implicit lifetime, or an ambiguous side effect.

In this case, Rust forced us to identify the real unit of mutation. It was not one entity and it was not whichever object happened to receive save. It was the set of pending changes attached to a shared object graph.

Once that was explicit, the design became easier to explain, test, and port. The surprising benefit was not merely that the Rust runtime worked. The other runtimes acquired a stronger contract too.

From One Rust Problem to Seven Conforming Runtimes​

TeaQL now applies the same mutation-ledger semantics in Rust, Java, Python, Go, .NET, Swift, and TypeScript. The APIs remain idiomatic to each language, but the observable behavior is shared: graph-wide roots, final field values, original versions, new/delete classification, checker-before-provider behavior, and clear success and failure transitions.

We retain executable cross-language evidence in the TeaQL conformance repository, rather than treating matching documentation as proof. The current fixture constructs or loads a parent with children, mutates both entity types, updates one field twice, marks a child for deletion, and saves through the ordinary audited path. It checks the ledger before save, the provider commands during save, and ledger state after rejection or success.

The implementation began in TeaQL Rust. The other six implementations—Java, Python, Go, .NET, Swift, and TypeScript—then adopted the same design.

What started as a solution to Rust's mutation constraints became one of the clearest pieces of our cross-language runtime architecture. Rust did not merely make us work harder. It made the hidden contract visible—and once visible, the contract could finally become consistent.

This gap is often described as a knowledge-access problem. Give the model the right documents, retrieve the right passages, and it will know what to do.

Retrieval is necessary, but it is not sufficient.

The real enterprise question is not only:

Can the AI find the knowledge?

It is:

Can the AI turn that knowledge into a correct, verifiable, and constrained capability?

Our work with TeaQL suggests a three-layer answer: Skill, Build Harness, and Runtime Harness. A Skill keeps the agent's direction and method sound. A Build Harness makes the constructed artifact mechanically verifiable. A Runtime Harness keeps actual execution inside engineering, security, permission, resource, and audit boundaries.

Together, these layers provide a practical way to give AI capabilities that do not exist inside the model itself.

Knowledge Is Not Yet Capability​

Suppose an experienced engineer knows how to respond to an unusual vibration pattern in a machine. The correct response may depend on load, temperature, lubrication state, recent maintenance, and the cost of an unnecessary shutdown. A document can record those factors. Retrieval can place the relevant paragraph in the model's context.

But professional capability involves more than repeating that paragraph. The engineer must:

• recognize when the procedure applies;
• gather the required evidence;
• distinguish a warning from a critical condition;
• use approved diagnostic operations;
• respect authority and safety boundaries;
• produce a decision that another person can inspect;
• act only when the evidence and permission are sufficient.

The same distinction appears in software delivery. An AI may retrieve a database convention or a domain rule and still invent a method name, omit a tenant boundary, save an invalid object graph, or run an unsafe operation. It has access to knowledge, but it does not yet possess a reliable capability.

This distinction matters most for knowledge that was never present in model training:

• private enterprise policies and operating procedures;
• domain-specific methods and terminology;
• proprietary workflows and decision rules;
• local architecture conventions;
• engineering lessons learned from previous incidents;
• tacit review standards used by experienced practitioners.

These are not special cases. They are where much of an organization's real advantage lives.

RAG Finds Knowledge; Harness Engineering Operationalizes It​

Retrieval-augmented generation is well suited to locating relevant information:

Question
  -> Retrieval
  -> Relevant private context
  -> Model response

It can answer, “Which policy applies?” or “What does our design guide say?” It can reduce hallucination caused by missing context and make private documents available without retraining a foundation model.

However, retrieval does not by itself answer several harder questions:

• Did the agent apply the correct procedure?
• Is the produced model or code structurally valid?
• Does the result preserve domain invariants?
• Is the requested action permitted for this identity and tenant?
• Are resource limits and side effects controlled?
• Can the organization reconstruct what happened and why?

Harness engineering addresses this next step:

Private knowledge
  -> Procedural guidance
  -> Constrained construction
  -> Verification
  -> Governed execution
  -> Evidence

RAG and harness engineering are complementary. RAG supplies relevant context. A harness turns context into an operating discipline, an executable artifact, and a controlled action.

The Three-Layer Method​

The method can be summarized as:

Skill
  keeps direction and method correct
        ↓
Build Harness
  makes the constructed artifact correct
        ↓
Runtime Harness
  keeps actual execution correct

Each layer addresses a different failure mode. None can substitute completely for the others.

Layer 1: Skill Keeps Direction and Method Correct​

A Skill gives the agent a compact operating method. It explains the goal, the important stages, the evidence to inspect, when to use a Tool, when to repair a result, and when human judgment is required.

For example, an internal incident-response Skill might tell the agent to:

1. identify the affected service and business impact;
2. gather current telemetry before proposing a cause;
3. compare the evidence with known failure patterns;
4. use read-only diagnostics before considering a mutation;
5. escalate when the proposed action crosses a declared risk threshold;
6. record the evidence behind the conclusion.

This is far more useful than a collection of retrieved paragraphs because it organizes knowledge into a procedure.

But a Skill remains guidance expressed in language. It can influence a probabilistic model; it cannot guarantee that every required field exists, every invariant holds, or every prohibited action is blocked. As Skills grow into exhaustive rule catalogs, they also compete for context, drift away from the implemented system, and become harder for the model to apply consistently.

The right role for a Skill is therefore stable direction and method—not mechanical enforcement.

Layer 2: The Build Harness Makes the Artifact Correct​

Once the agent begins constructing something—a domain model, application, workflow, configuration, report, or decision package—correctness must move into executable feedback loops.

A Build Harness may include:

• schemas and type systems;
• domain-specific languages;
• linters and static analyzers;
• policy evaluators;
• deterministic generators;
• compilers;
• unit, integration, and acceptance tests;
• simulations and benchmark cases;
• structured error reports that support repair.

These mechanisms do not merely tell the agent what correctness means. They test the artifact and return evidence.

Agent proposes an artifact
  -> Evaluate
  -> Return structured failures
  -> Repair
  -> Re-evaluate
  -> Generate or package
  -> Test

This loop is especially important when teaching an AI a new technology or an internal engineering method. A long prompt can describe the method, but a validator can reject an invalid representation. A compiler can detect an invented interface. A test can prove that a critical scenario works. A deterministic generator can preserve rules the model should not reproduce from memory.

The build layer changes the meaning of “the AI knows how to do it.” The claim no longer depends only on whether the model can produce a convincing answer. It depends on whether the result passes the organization's executable definition of correctness.

Layer 3: The Runtime Harness Keeps Execution Correct​

A correct artifact can still be used incorrectly.

Production execution introduces identity, authority, current state, concurrency, resource limits, sensitive data, side effects, and failure recovery. These conditions cannot be settled permanently during generation. They must be enforced when an action is attempted.

A Runtime Harness provides controls such as:

• authenticated identity and request context;
• authorization and tenant boundaries;
• approved, semantically narrow Tools instead of unrestricted access;
• transaction and state-transition guards;
• input, output, and policy validation;
• rate, time, memory, and cost limits;
• sandboxing and network boundaries;
• approval gates for consequential actions;
• idempotency, rollback, and recovery mechanisms;
• logs, provenance, and audit evidence;
• monitoring and the ability to stop execution.

This layer answers questions that no Skill can reliably answer in prose: Does this user have permission now? Is this transition valid from the current state? Has the spending limit been reached? Is the target inside the approved environment? Can the exact action and its justification be reconstructed later?

The Runtime Harness is where advice becomes authority-aware action.

TeaQL as a Concrete Case​

TeaQL is useful here not because every enterprise should adopt the same technology, but because it makes the three layers visible in one engineering workflow.

The TeaQL agent workflow begins with a lightweight Skill. The Skill directs the agent to understand the business requirement, express it as a typed domain contract, evaluate the contract, repair reported problems, generate the application, and provide concrete completion evidence. It describes the path without attempting to embed every modeling and programming rule in the prompt.

The build layer then carries the detailed correctness burden. The Generation Service evaluates the domain model and returns structured reports. Deterministic generation projects an accepted model into code and model-aware APIs. Generated local guidance exposes the current interfaces. Compilers and tests reject invented methods, invalid types, and broken behavior.

The runtime layer constrains what the resulting application can do. Queries and writes execute through a user context. Read operations carry purpose and comments; mutations carry audit descriptions. Provider and repository boundaries control persistence. Policies, tenant rules, generated business APIs, and runtime checks sit between AI-generated application logic and the underlying data systems.

In simplified form:

Business requirement
  -> Skill-guided domain modeling
  -> Evaluation and repair
  -> Deterministic generation
  -> Compiler and test evidence
  -> User-context execution
  -> Policy, permission, and audit controls

The important result is not that the model memorizes TeaQL. It is that a general-purpose model can use a capability that was not part of its training, while detailed rules remain in the systems best able to enforce them.

This is also why the case should not be reduced to code generation. The same architecture applies whenever professional knowledge must cross the boundary from explanation to responsible execution.

From Internal Knowledge to Executable Knowledge​

Consider four examples.

An insurance company may have a proprietary claims-review method. RAG can retrieve the policy and prior cases. A Skill can define the review sequence. A Build Harness can validate that the decision package contains the required evidence and calculations. A Runtime Harness can enforce adjuster authority, protect customer data, and audit the final action.

A manufacturer may have an internal process for diagnosing equipment. A Skill can guide evidence collection. Diagnostic Tools and simulations can verify the proposed intervention. Runtime controls can prevent an agent from changing machine parameters outside an approved range.

A bank may have a private credit-exception workflow. Retrieval can provide policy context. A Skill can distinguish ordinary assessment from exception handling. Validators can check the completeness and consistency of the case. Runtime permissions and approval gates can ensure that a recommendation does not become an unauthorized decision.

A software organization may have years of engineering experience encoded across code review comments, incident reports, and unwritten conventions. A Skill can express the stable workflow. Build checks can enforce architectural rules and test critical cases. Runtime boundaries can restrict deployment targets, secrets, infrastructure changes, and production access.

In every example, the useful transformation is:

Information
  -> Procedure
  -> Verifiable artifact
  -> Constrained action
  -> Auditable evidence

That is what it means to turn organizational knowledge into executable knowledge.

Where Each Rule Should Live​

A practical design test is to ask what kind of rule has failed:

When a failure repeats, adding another paragraph to a prompt is rarely the strongest long-term fix. Stable procedural guidance belongs in a Skill. Domain meaning belongs in an explicit model. Mechanical correctness belongs in validators and tests. Authority and side-effect control belong at runtime.

This division keeps the model's context smaller while making the surrounding system stronger.

A Capability Formula for Enterprise AI​

The method can be expressed as a compact systems formula:

Enterprise AI Capability
  = Foundation Model
  + Domain Context
  + Skill
  + Build Assurance
  + Runtime Assurance

The foundation model contributes general reasoning and generation. Domain context supplies knowledge the model did not contain. The Skill provides operating method. Build assurance makes artifacts verifiable. Runtime assurance makes real actions governable.

If any of the later layers is missing, the system tends to fall back into one of two weak modes: an AI that can discuss the organization's knowledge but cannot reliably act, or an AI that can act but cannot be trusted with consequential work.

The Next Step After Retrieval​

Enterprise AI is moving through three progressively harder questions:

Knowledge:  Can the model know?
Retrieval:  Can it find the relevant private knowledge?
Execution:  Can it apply that knowledge correctly and safely?

The third question is not solved by a larger context window or a better search index alone. It requires engineering around the model.

TeaQL offers one concrete example of that transition: lightweight procedural guidance, deterministic construction and verification, and a constrained runtime boundary. The broader method is technology-independent. Any organization can apply it to its own internal knowledge, specialist methods, proprietary processes, and accumulated engineering experience.

The goal is not to make a foundation model contain every organization's expertise. The goal is to build systems through which a capable model can use expertise it was never trained on—and do so with evidence, limits, and accountability.

Consider this request:

Find customers who placed more than three orders in the last 30 days, have a refund rate above 20%, and still have an unresolved support ticket.

A conventional application may not have an endpoint for that exact question. A model with unrestricted SQL access could try to construct it, but it would also need to know the physical schema, joins, enum encodings, tenant filters, authorization rules, soft-delete conventions, and database dialect. That is a large and dangerous contract to place in a prompt.

TeaQL offers a different boundary:

Give the model composable business semantics, not database authority.

TeaQL sits above SQL dialects as a governed business query language. The model can combine approved domain concepts into a query that has never been exposed as a dedicated endpoint, while the application retains control of identity, permissions, limits, audit, and execution.

The Gap Between Fixed APIs and Raw SQL​

Most agent-to-data integrations begin at one of two extremes.

At one extreme, the application exposes a fixed set of narrow API operations:

getCustomerById
listOpenOrders
findOverdueInvoices

These operations are easy to govern, but their composition space is limited. Every new question may require another endpoint, deployment, and integration.

At the other extreme, the application gives the model a generic SQL tool:

executeSql(sql: string)

This is flexible, but the abstraction boundary is wrong. SQL exposes storage mechanics rather than business capabilities. A syntactically valid query can still violate tenant isolation, reveal sensitive fields, scan an unreasonable amount of data, or encode the wrong business meaning.

TeaQL occupies the space between them:

The objective is not unrestricted flexibility. It is governed query composition.

SQL Describes Storage; TeaQL Describes the Business​

SQL is excellent at describing how to retrieve and transform rows. It speaks in tables, columns, joins, predicates, grouping, ordering, and database-specific functions.

An agent working on behalf of a user needs a different vocabulary:

• Customer, Order, Refund, and Support Ticket;
• active, overdue, unresolved, and eligible;
• relationships between business objects;
• fields that may be filtered, projected, aggregated, or sorted;
• the current user's tenant and permitted data scope;
• the purpose of the query and the limits of the operation.

TeaQL maps that business vocabulary to generated, typed query APIs. Database providers remain responsible for translating the resulting request into the appropriate SQL and parameter representation.

Natural-language request
  -> model-selected business query
  -> TeaQL domain semantics and runtime policy
  -> PostgreSQL, MySQL, Oracle, SQL Server, SQLite, or another provider

The database still executes SQL. The important change is that SQL is no longer the contract between the model and the application.

New Queries Without New Database Authority​

Dynamic query composition matters because users rarely ask only the questions that developers predicted.

A TeaQL query can combine declared capabilities such as:

• filters over typed business properties;
• relationship traversal and nested selection;
• projection of an approved field set;
• sorting, pagination, grouping, and aggregation;
• reusable domain predicates;
• runtime policies applied through the current context.

These pieces can express a new question without creating a new repository method for every combination.

The model should not emit TeaQL source code directly. Instead, it should call a tool with a constrained, machine-readable query specification. The server validates that specification and maps it to generated TeaQL APIs.

{
  "entity": "Order",
  "filters": [
    { "field": "status", "operator": "is", "value": "PAID" },
    { "field": "createdAt", "operator": "after", "value": "2026-08-01T00:00:00Z" }
  ],
  "select": ["id", "customerName", "createdAt"],
  "orderBy": [{ "field": "createdAt", "direction": "desc" }],
  "limit": 20
}

This is not a second textual query language for the model to improvise. It is a validated capability document. Only registered entities, fields, operators, relations, and limits are accepted.

The Model Does Not Receive Trusted Context​

The model proposes what it wants to query. The server decides under whose authority the query runs.

TeaQL execution uses a trusted context selected by the application. It can carry identity, tenant, authorization policy, data services, audit facilities, and other runtime resources. That context is captured server-side and is never accepted as model input.

Model-generated query specification
  -> schema and capability validation
  -> server-owned context
  -> authorization and tenant policy
  -> TeaQL request execution
  -> bounded, projected result

This separation prevents the model from choosing another tenant, replacing a data service, or granting itself a permission through tool arguments.

Governance Is More Than Preventing Bad SQL​

Removing raw SQL is useful, but it is not the complete security model. A governed business query also needs explicit decisions about:

• which entities and relationships an agent may use;
• which fields may be filtered or returned;
• which operators and aggregates are available;
• maximum page size, traversal depth, and execution cost;
• sensitive-field masking and result projection;
• authorization and tenant isolation;
• query purpose, audit metadata, and telemetry;
• safe error messages returned to the model.

The model's prompt is guidance. These controls belong in deterministic server code and runtime policy.

The useful distinction is:

SQL permissions answer what a database connection can execute. TeaQL capabilities answer what this user, through this agent, may do in this business context.

Dynamic Reads, Explicit Business Actions​

The freedom to compose reads should not imply arbitrary writes.

Queries are naturally exploratory. Within declared limits, it is reasonable for an agent to combine filters and projections to answer a new question. Mutations have different risks: they may trigger workflows, violate state transitions, affect money, or require human confirmation.

TeaQL therefore benefits from an asymmetric boundary:

Read request
  -> constrained dynamic query
  -> validation and policy
  -> bounded result

Write request
  -> explicit business action
  -> input validation
  -> user approval when required
  -> authorization and domain validation
  -> audited save

An agent may dynamically discover orders that qualify for review. Creating a refund, approving it, or closing an order should still happen through explicit actions such as createRefundRequest, approveRefund, or closeOrder.

This preserves useful query flexibility without turning the agent into a general-purpose database administrator.

One Business Language Across Runtimes and Databases​

Database portability is often described as hiding placeholder syntax or pagination differences. For agents, the larger benefit is semantic stability.

The same business concept should retain its meaning when an application moves between database providers or when a TeaQL service is implemented in a different supported language. The model-facing tool should not need to learn whether a timestamp comparison becomes a PostgreSQL expression, an Oracle expression, or a SQLite expression.

That creates a layered contract:

Models and database providers can change independently while the business language remains recognizable.

A Practical Agent Interaction​

Suppose a user asks:

Show me secondary schools created this year whose contact phone is missing.

The interaction can follow this path:

1. The model selects an approved school-search tool.
2. It supplies typed filters for school type, creation date, and an explicitly null contact phone.
3. The server validates the query against the published capability schema.
4. The application attaches its trusted TeaQL context.
5. Runtime policy applies authorization, tenant filters, projection, and result limits.
6. The database provider executes parameterized SQL in its own dialect.
7. The tool returns a bounded business result, not unrestricted database rows.
8. The model explains the result to the user.

If the user then asks the agent to update a phone number, the agent switches to an explicit write capability with validation, approval, and audit.

The Role of @teaql/ai-sdk​

The TeaQL AI SDK is designed to connect TeaQL business capabilities to model tool calling. It complements an agent SDK; it does not provide a model or replace the agent loop.

The agent SDK handles model providers, conversations, streaming, and tool-call orchestration. TeaQL provides the business-data boundary underneath:

Model and agent loop
  -> TeaQL AI SDK tools
  -> TeaQL runtime context and policy
  -> business data

For a concrete example of explicit capabilities, approval, server-owned context, safe failures, and audited writes, read Build a Safe SQL Agent Without Giving the Model SQL Access.

Beyond the Dialect Boundary​

TeaQL does not need to replace SQL to move the application boundary above it. SQL remains an effective execution language for relational databases. TeaQL provides the stable business language that applications and AI agents can use without depending directly on physical schema or dialect.

The resulting proposition is simple:

Ask questions your application has never implemented, without giving AI unrestricted SQL access.

Or, in architectural terms:

TeaQL is a governed business query language above SQL dialects: composable like a query, governed like an application API, and designed for AI agents.

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 is taking a different path. We are designing internationalization as part of the application infrastructure: explicit in UserContext, structured before rendering, consistent across six programming languages, and constrained strongly enough that both people and coding agents can extend it without inventing a new architecture at every call site.

This work is still in design and is not yet a released portable TeaQL capability. This article explains why we believe the design is worth doing, the trade-offs we are making, and the kinds of organizations that benefit from it.

The problem is not translating a string​

Mature applications execute work through many paths:

• an HTTP request;
• a command-line tool;
• a background job;
• a message consumer;
• a scheduled process;
• a federated call between services;
• a test or an AI-operated development harness.

If each entry point discovers the locale independently, internationalization becomes transport-specific. The controller reads Accept-Language; the job uses an application default; a message consumer receives a language field; another service falls back to the operating system; and a test quietly depends on the developer's machine.

Every individual implementation may appear reasonable. Together they create several incompatible sources of truth.

The problem becomes more serious when an application returns only rendered text. Consider a validation failure reduced to this response:

{
  "message": "工作时长是必填项"
}

The consumer can no longer reliably determine the error identity, affected field, typed arguments, or whether fallback occurred. Another API consumer cannot render it differently without parsing a sentence. Logs and tests become coupled to wording that translators should be free to improve.

The hard problem is therefore not string lookup. It is preserving meaning and context across the entire execution path.

One place for runtime context​

TeaQL already treats UserContext as the explicit carrier of runtime information. Internationalization should follow the same rule.

application-specific inputs and override rules
                    ↓
       initialize one UserContext
                    ↓
 validation, translation, API output, jobs, and federation

The logical internationalization state in UserContext separates two concerns:

• LocalizationConfiguration describes supported locales, defaults, fallback rules, catalogs, output mode, and safety policy.
• LocalizationPreference describes the locale, time zone, currency, and formatting choices desired for the current execution.

Configuration and preference are allowed to differ. Applications can replace either while initializing UserContext. A Web adapter might consider a validated request header; a background process might use a configured preference; a test might construct both directly. TeaQL does not prescribe one universal precedence algorithm for those application inputs.

After initialization, translation reads only UserContext. It does not query HTTP headers, authentication records, databases, thread-local state, or process defaults. It has no concept of the business source from which the application derived a preference.

This boundary costs a little convenience. Every execution path must propagate UserContext correctly. We accept that cost because explicit propagation is observable, testable, and portable across runtimes with very different concurrency models.

Preserve meaning before rendering​

TeaQL messages should remain structured until a deliberate rendering boundary. A validation result can retain:

{
  "code": "REQUIRED",
  "path": ["timesheet", "workedHour"],
  "message": {
    "key": "validation.required",
    "arguments": {
      "field": {
        "term": "entity.Timesheet.field.workedHour"
      }
    }
  }
}

The stable code, key, field path, and typed argument names form the contract. Rendered text is a presentation derived from that contract.

This leads to three useful API modes:

• STRUCTURED lets a client or downstream service own rendering.
• RENDERED serves consumers that want ready-to-display text while retaining stable identity.
• BOTH carries the structured message and rendered result, which is useful for migration and diagnostics.

The effective mode is also part of UserContext. An API adapter may map an explicitly allowed consumer preference into the context during initialization, but unrestricted dynamic input and ordinary federation payloads cannot rewrite the established policy.

Models contain language-sensitive meaning​

TeaQL is model-driven, so internationalization cannot stop at application error strings. The model contains entities, properties, relations, actions, and query predicates that users eventually see.

Generated descriptors can give these concepts stable identities without putting translated sentences into generated source files. Application catalogs can then override generated or framework text without being overwritten by regeneration.

Natural-language details matter here. Pluralization is not appending s or es. Human and non-human subjects may require different predicates. A plural human collection may read “Who are active?”, while an attributed predicate may use “Whose email is …”. These are language semantics, not naming shortcuts.

We want the generator to provide stable descriptors and reviewed grammatical intent. We want translators and mature localization engines to control the final sentence.

What TeaQL should own—and what it should not​

TeaQL should own the portable application contract:

• where localization state lives;
• how configuration and preference are represented;
• stable message and term identities;
• typed arguments and field paths;
• deterministic fallback and catalog precedence;
• structured federation behavior;
• observability and privacy rules;
• the conformance corpus shared by all runtimes.

TeaQL should not invent a new set of plural, date, number, currency, or grammatical rules. ICU, CLDR, Fluent, and mature language ecosystems already contain deep expertise in those areas. The portable TeaQL subset should be implemented on top of proven facilities where possible.

This division is important. A proprietary formatter would quickly diverge across Java, Rust, Go, Python, C#/.NET, and TypeScript. A shared semantic contract backed by established formatting engines gives us both portability and linguistic depth.

Shared runtimes create an opportunity for shared governance​

Supporting six languages creates a problem if every runtime also creates an independent language site. An enterprise could end up translating the same entity, field, action, and validation concept six times—and still use different terminology in each product.

We see an opportunity to treat terminology as governed application metadata. A centralized TeaQL console can receive generated model descriptors and manage:

• stable identities and approved display names for domain concepts;
• definitions and usage guidance for enterprise vocabulary;
• human/non-human and other grammatical metadata;
• locale variants and translator context;
• ownership, review, approval, publication, and rollback;
• catalog versions, hashes, and compatibility information;
• conflicts, missing translations, and affected applications.

The workflow becomes:

models and application descriptors
              ↓
central terminology and catalog console
 author → review → approve → publish
              ↓
versioned catalog snapshots
              ↓
Java · Rust · Go · Python · .NET · TypeScript

This is more than centralized storage. It allows an organization to decide once what a business concept means and how it should be presented, then make that decision observable and consistent across language stacks. A terminology change has an owner, a review record, an immutable version, an impact report, and a rollback path.

The console is a control plane, not a synchronous dependency of every translation. Runtimes consume versioned, content-addressed catalog snapshots and select the active registry through UserContext. Applications remain available when the console is unavailable, and a rendered result can report exactly which catalog version produced it.

This separation preserves the runtime boundary: translation still knows only UserContext and published catalogs. It does not learn about the organizational systems that authored or approved them.

Six languages change the standard of correctness​

Implementing the feature in Java is not enough. TeaQL supports Java, Rust, Go, Python, C#/.NET, and TypeScript, and the same application meaning must survive all six.

We therefore plan one shared conformance corpus covering:

• locale normalization and deterministic fallback;
• missing and malformed catalogs;
• named and typed arguments;
• plural, ordinal, selection, and term behavior;
• numbers, dates, currencies, and time zones;
• generated domain labels and validation paths;
• human and non-human predicates;
• catalog overrides and cache invalidation;
• direct and federated parity;
• trusted-context protection;
• pseudolocalization and right-to-left text.

The goal is not identical internal code. Each runtime should feel natural in its own language. The goal is identical observable semantics.

AI makes architectural boundaries more important​

Coding agents are very good at extending a visible pattern. When no pattern is explicit, they are equally capable of creating locally convincing architecture drift.

An agent asked to localize one endpoint may read a header directly, add a locale parameter, translate an exception into a string, and use the machine default when no value is available. The change may pass its local test. Repeated across a codebase, it creates a system that nobody intentionally designed.

TeaQL's response is not to ask every agent to rediscover the architecture. The framework should make the safe path obvious and the wrong path difficult:

1. Internationalization state belongs in UserContext.
2. Translation, validation, and execution do not gain a second locale or policy parameter.
3. Entry-point adapters initialize the same context contract.
4. Structured error identity is never replaced by localized prose.
5. Unsupported or forbidden input fails explicitly instead of selecting an accidental fallback.
6. Every runtime must pass the same portable fixtures.

These constraints will eventually become maintained agent rules in the generator as well as runtime APIs and tests. Documentation explains the architecture; generated guidance puts it in front of coding agents; types and conformance tests enforce it.

Where this matters most​

The clearest beneficiaries are organizations whose systems already span multiple languages and infrastructure generations. A core transaction platform may use Java, performance-sensitive services Rust, cloud services Go, AI workloads Python, internal enterprise systems .NET, and application edges TypeScript.

Without a shared contract, each ecosystem gradually develops its own interpretation of context, validation, errors, audit, pagination, and localization. The cost is not visible in the first service. It appears years later as duplicated platform work, inconsistent behavior, and migrations that cannot be verified.

For platform-engineering teams, TeaQL can provide a paved road that is broader than one framework template. Teams keep language-appropriate APIs while inheriting the same application guarantees. New languages and infrastructure can enter without resetting the organization's governance and semantics.

Long-lived software products also benefit. Their technology stacks rarely remain frozen for a decade. A stable, model-driven contract allows the product to evolve without turning each new runtime into an independent application platform.

This does not mean a new or single-language system has nothing to gain. Explicit context, structured errors, generated descriptors, deterministic behavior, and AI-oriented guardrails are valuable before a second language arrives. Such a system can start with one runtime while avoiding assumptions that make later growth expensive.

The primary value, however, becomes most visible when organizational and technical diversity are unavoidable: languages may differ, but application meaning should not.

The goal is durable evolution​

TeaQL is not trying to become another translation-string library. We are designing a model-driven internationalization and context layer that can remain coherent across languages, execution paths, APIs, and coding agents.

That is a larger commitment than adding translate(key). It requires a portable schema, runtime integrations, generated descriptors, federation rules, shared fixtures, and release evidence. It also gives us something much more durable: an application can evolve its languages, databases, frameworks, and infrastructure without allowing its meaning to fragment at the same rate.

The complete proposal is available in the Internationalization Design Baseline. The development warning will remain until the portable contract is implemented and verified across the supported runtimes.

npm install @teaql/teaql

The package contains the core runtime and explicit SQL entry points for PostgreSQL, MySQL, and SQLite. Install only the database driver your application uses:

npm install @teaql/teaql pg pg-query-stream       # PostgreSQL
npm install @teaql/teaql mysql2                    # MySQL
npm install @teaql/teaql better-sqlite3            # SQLite

The published artifact was built and tested with Node.js 22. We also installed it from the public registry into a clean project and loaded the main, SQL core, PostgreSQL, MySQL, and SQLite exports.

This release makes the same runtime used by TeaQL's generated TypeScript applications available through the standard Node.js package workflow. Source, issues, and release development remain in the teaql-ts repository.

Future releases are configured to publish from GitHub Actions through npm Trusted Publishing, using short-lived OIDC credentials instead of a stored long-lived npm publishing token.

For a collection of people, TeaQL uses whoAreActive(), not whoIsActive(). For an ordinary human attribute it uses whoseEmailIs(...). A non-human entity uses whichAreActive() and withCodeIs(...).

These forms sound related, but they solve different problems: whose expresses possession, while who are agrees with the plural result set.

Humanity must be declared​

TeaQL classifies an entity as human only when the model explicitly declares cat="human". The generator does not infer it from names such as customer, user, employee or person.

This avoids cultural guesses and domain ambiguity. A user may be a service account; a customer may be an organization. The model owns the semantic decision.

One vocabulary, six casing conventions​

Java generated Request APIs are the semantic gold standard. Other languages preserve the same meaning and adapt casing only:

Boolean fields should preferably be adjectives such as active. A field named is_active pushes grammar into schema naming and tends to generate repeated Is fragments.

Why this needed a generator-level test​

Several target templates once hard-coded with, bypassing the human classification. Java also had a remaining singular boolean form. Fixing examples would not have fixed generated APIs.

We centralized predicate naming and added paired fixtures: a human person and a non-human device, both with equivalent string, scalar and boolean fields. The six-language test requires forms equivalent to whoseEmailIs, withCodeIs, whoAreActive, whoAreNotActive and whichAreActive, while rejecting whoIsActive.

The lasting rule is simple: semantic vocabulary comes from the model and generator core, never from a target template's intuition.

That approach does not scale.

Our practical conclusion is different:

Keep Skills lightweight. Make Tools strong.

This is not an argument for fewer safeguards. It is an argument about where safeguards belong.

It is also a principle for harness engineering. The core of an agent harness should not be an ever-growing library of Skills. It should be a set of strong, model-aware Tools and deterministic feedback loops that turn guidance into enforceable action boundaries.

The Vehicle Analogy​

An AI agent can be understood as a vehicle operating in the real world:

1. The large language model is the engine. It supplies the general power to understand language, reason, plan, and generate possible actions.
2. Skills are the traffic rules. They prescribe how the agent should conduct itself: which procedures to follow, when to inspect or yield, what evidence is required, and which actions are prohibited.
3. Tools are the steering wheel and brakes. They determine where the agent can actually direct its power, which actions it can execute, and where execution must stop.
4. The world model is the map. It describes which places exist, how they are connected, which routes are possible, and how the reachable world changes over time.

Agent vehicle
  Engine              = LLM
  Traffic rules       = Skills
  Steering and brakes = Tools
  Map                 = World Model

An engine can produce motion, but it cannot define the world, choose a valid route, or stop itself safely. Traffic rules can guide behavior, but prose alone cannot steer or brake the vehicle. A map can describe the available space, but it cannot execute an action.

Reliable agency emerges only when these four responsibilities remain distinct and work together.

Why Skills Should Stay Lightweight​

A Skill should describe stable operating discipline:

• the objective of the workflow;
• the stages the agent should follow;
• when it should inspect, evaluate, repair, or escalate;
• which evidence is required before declaring success;
• how feedback should influence the next step.

It should not try to become a second implementation of every system it uses.

When detailed domain rules are copied into Skill prose, several problems appear:

• the instructions become too large to load and apply consistently;
• the same rule exists in both prose and executable software;
• documentation and runtime behavior drift apart;
• failures lead to more prompt patches rather than better system boundaries;
• compliance depends on the model remembering an instruction at the right moment.

Adding more Skills introduces a second problem: context competition. Each Skill consumes context, introduces terminology, and adds rules that the model must retrieve and reconcile during the task. As the collection grows, relevant instructions compete with irrelevant ones, overlapping Skills may disagree, and the agent has less attention available for the actual state of the problem.

More importantly, Skills are text. They can influence behavior, but they cannot guarantee behavior. An agent may misunderstand a rule, apply it at the wrong time, lose it in a long context, or choose a plausible action that the Skill never anticipated. No amount of prose can ensure complete compliance from a probabilistic model.

If a rule must always hold, it cannot live only in a Skill.

Traffic rules should be clear and economical. They should not attempt to reproduce the engine, the controls, or the map.

What Makes a Tool Strong​

A strong Tool is not a large Tool, and a strong toolset is not necessarily a large collection of Tools.

A Tool is strong when it exposes a narrow, semantically meaningful operation with:

• explicit inputs and outputs;
• clear authority and permission boundaries;
• known side effects;
• deterministic validation where possible;
• actionable failure feedback;
• audit evidence and provenance;
• traceability from intent to result.

The steering-wheel part directs power toward a valid action. The brake part prevents or rejects an invalid action. Both are necessary.

A generic execution shell may be powerful, but it provides little semantic steering. A domain-aware operation such as evaluate model, approve payment, or generate from accepted specification offers a much stronger control surface. It tells the agent what kind of action exists, what it requires, and how success or failure will be judged.

The strongest Tool does not merely execute what the model asks. It helps constrain the space of askable actions.

Strong Tools Are the Core of Harness Engineering​

An agent harness is the engineered environment around the model. It determines what context is supplied, what actions are available, how actions are validated, what feedback is returned, and what evidence is required before work is considered complete.

In that environment, Skills are useful—but they are not the enforcement layer. They provide compact procedural guidance. The core control surface is the Tool layer.

A strong harness moves critical behavior out of optional textual compliance and into executable structure:

• schemas reject malformed inputs;
• permissions prevent unauthorized actions;
• domain Tools expose valid operations instead of raw implementation access;
• evaluators reject invalid models and explain why;
• generated APIs prevent the agent from inventing interfaces;
• state machines disallow invalid transitions;
• compilers and tests reject inconsistent implementations;
• runtime guards enforce policies at the moment of execution;
• audit trails record what happened and why.

Skill
  suggests the procedure
       ↓
Agent
  reasons and proposes an action
       ↓
Strong Tool
  constrains, validates, executes, or stops
       ↓
Harness Feedback
  returns evidence for the next reasoning step

This is the essential difference between instructions and a harness. An instruction says, “Do not cross this boundary.” A harness makes the boundary difficult or impossible to cross, detects the attempt, and returns structured feedback.

The goal is not to eliminate agent judgment. It is to focus that judgment where semantics are genuinely uncertain while moving mechanical correctness into deterministic controls.

For that reason, harness engineering should prioritize better Tools over more Skills. When a failure repeats, the durable fix is usually not another paragraph. It is a narrower interface, a stronger validator, a clearer state model, a permission boundary, or a better feedback signal.

The World Model Defines the Reachable Space​

Tools determine how an agent acts, but the world model determines what the agent believes it can act upon.

A useful world model explains:

• which concepts exist;
• which relationships connect them;
• which events can change those relationships;
• which constraints make an event or state valid;
• which states are currently reachable;
• what would change if a proposed action occurred.

Without that map, an agent may operate its controls correctly and still drive toward an invented destination. It may call a valid API while misunderstanding the meaning of the entity, role, state, or transition behind it.

The world model therefore limits and explains the action space. It gives both Skills and Tools a shared semantic reference.

From Probabilistic Understanding to Deterministic Results​

LLM reasoning is probabilistic. That does not mean the resulting software process must be probabilistic from end to end.

A more reliable workflow is:

Human Intent
  -> Model
  -> Deterministic Evaluation
  -> Repair
  -> Deterministic Generation
  -> Constrained Customization
  -> Verification

The model is audited before it becomes executable. Errors are returned as structured feedback. The agent repairs the model and submits it again. Once accepted, deterministic generation projects that model into code and model-aware APIs. Later customization occurs through those constrained interfaces and is checked again by compilers, tests, policies, and runtime guards.

This creates an important separation:

• AI interprets intent and proposes semantic changes;
• the harness supplies the relevant context and available action space;
• deterministic Tools evaluate, generate, constrain, and verify;
• the accepted model remains the traceable source of meaning.

The result is not code that merely happened to be produced by an AI. It is a deterministic artifact derived from an audited semantic model, followed by customization inside explicit boundaries.

Our work with TeaQL was one practical source of this conclusion: repeated model evaluation and repair produced deterministic generated code and a constrained path for subsequent customization.

Feedback Belongs in the System​

When an agent makes a mistake, the default response should not always be to add another sentence to its Skill.

First ask where the missing knowledge or enforcement belongs:

• If it is stable operating guidance, improve the Skill.
• If it defines the domain, improve the world model.
• If it controls what can be executed, improve the Tool.
• If it is mechanically verifiable, improve the evaluator, compiler, test, policy, or runtime guard.

This turns failure into system improvement instead of prompt accumulation.

The feedback loop becomes:

Attempt
  -> Tool Feedback
  -> Model or Implementation Repair
  -> Re-evaluation
  -> Verified Result

The agent still reasons and adapts, but it does not carry the entire burden of correctness in its context window.

This is how the harness becomes more capable without becoming a larger prompt: repeated failures improve the executable environment rather than permanently expanding the text the agent must remember.

A Better Division of Responsibility​

The architecture can be summarized in four lines:

The LLM provides the power.
Skills define the rules of conduct.
Tools provide steering and braking.
The world model defines the reachable world.

“Lightweight Skills, Strong Tools” is therefore not primarily a prompt-writing technique. It is the central design principle of a reliable agent harness.

Reliable agents will not come from developing more and more Skills and asking a language model to remember them all. They will come from combining capable models with concise operating rules, explicit maps of reality, and a strong harness whose Tools make valid actions controllable, invalid actions stoppable, and every consequential result verifiable.

plural = name + "s"

It works for order, which makes it look harmless. Then it produces order_statuss, categorys, persons, childs, and inventorys.

During TeaQL's six-language acceptance work, we found this assumption in Python and Go query templates and in a Rust diagnostic. The generated code compiled often enough for the mistake to survive until an entity ending in status exposed it.

The rule belongs above the templates​

TeaQL now treats plural names as generator metadata. Templates consume a centralized plural name and only transform its casing for the target language. They may not append s or es themselves.

That rule covers more than query entry points. It also applies to relation collections, sample-data methods, documentation examples, AI-assist prompts and diagnostics. Otherwise the generated API and the instructions used to call it eventually disagree.

An inflection library is a component, not the contract​

A library can handle common suffix rules but still choose a technically defensible word that is wrong for the public API. In our tests, the inflector returned persons; the TeaQL collection contract requires people.

The centralized policy therefore includes conventional irregular mappings and compound suffix replacement:

Regeneration is the compatibility strategy​

We did not retain wrong names as aliases. Generated APIs are cheap to regenerate, while every compatibility alias becomes a permanent maintenance and documentation cost.

The regression suite now generates regular, suffix-changing, irregular, compound and uncountable fixtures. It checks the current Java, Rust, Go, Python, .NET and TypeScript output instead of testing the pluralizer in isolation.

The lesson is broader than English grammar: templates should render reviewed naming decisions, not make linguistic decisions independently.

The next acceptance run closed that distinction. Java, Rust, Go, Python, .NET and TypeScript each executed the generated Order Search API against PostgreSQL, MySQL and SQLite: 18 of 18 core cells passed, representing 252 successful positive dynamic scenario executions.

What a complete core cell proved​

Each language/database cell executed empty, root, parent, child, range, combined, empty-result and stable-pagination queries plus an exact per-parent Top-N. Rows, record count, SUM and grouped facets shared the same active filter and used database-native COUNT, SUM and GROUP BY.

Top-N evidence showed a partition/window plan rather than application overfetch. Preset saves were tenant-scoped, audited, idempotent and versioned; stale versions were rejected. Purpose, comment and audit-reason gates were exercised through the real generated APIs.

Unknown fields, trusted-context override attempts, reversed ranges, wrong types, excessive IN/page size, deep paths, forbidden sorts and illegal offsets were rejected by the shared trusted endpoint validator before query construction. We report that boundary accurately rather than pretending each rejection was a language-specific SQL execution.

Governance was part of PASS​

All six runtimes now expose two distinct mutation audit paths:

1. a server-owned row or mutation audit path;
2. a separately attributable application audit sink receiving metadata-masked events.

The 18 core cells passed both paths. Application feature logging was not accepted as a substitute for runtime audit infrastructure.

Extended databases moved beyond persistence-only​

Java completed the full Feature on Oracle, DB2, DM8, SAP HANA, SQL Server and DuckDB. .NET completed the same Feature on SQL Server. These seven results cover stable pages, tenant isolation, exact Top-N, complete child counts, native aggregates, preset persistence, optimistic locking and governance—not only create/save/reconnect tests.

Snowflake remains BLOCKED_BY_ENVIRONMENT because the test environment lacks a complete account and authenticated user/context profile. A token alone was not treated as a connection profile, and no PASS was invented.

Federation used the real protocol​

The generated TypeScript client sent its query through TeaQL's Federal Protocol /query endpoint. The Rust server routed it through teaql-tfp-endpoint to the PostgreSQL-backed generated runtime. Direct Rust and federated responses had identical canonical IDs.

Client attempts to override tenant, merchant, user, permissions, request policy, purpose policy and trusted context were rejected. A generic HTTP wrapper was not counted as federation.

The result is intentionally scoped: every executable core and extended cell passed, while global status remains a GAP until Snowflake has a complete external connection environment. Evidence is valuable only when its boundary is as precise as its green cells.

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

The parity contract​

The final generator enforces these shared invariants:

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

Expressions revealed deeper differences​

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

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

Compile the generated result​

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

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

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

await request.execute_for_list(ctx)

There is no second data-service, provider or connection argument. Those dependencies—together with tenant identity, authenticated user, permissions and policy—are installed when the trusted context is initialized and resolved from it during execution.

Why a second argument is structurally wrong​

An API such as execute_for_list(ctx, service) creates two possible sources of runtime truth. The context may authorize one tenant while the separately supplied service points somewhere else. Even when today's implementation is safe, the shape invites future bypasses and inconsistent tests.

TeaQL therefore applies the context-only rule to list, one, entity-list, entity-one and mutation operations across Java, Rust, Go, Python, .NET and TypeScript. Required resources fail closed when context initialization omitted them.

An audit reason remains an explicit business intent value. It is not dependency injection.

Purpose is a type-state transition​

Comment and purpose have different roles:

• comment describes what operation is being performed and may appear anywhere in the builder chain;
• purpose explains why the application needs the read;
• after purpose, the Request transitions into an executable state.

A canonical flow is:

Q.orders()
  .comment("Find orders awaiting review")
  ...filters, sorting, selections...
  .purpose("Prepare the authorized review queue")
  .executeForList(ctx)

Comment does not have to sit immediately before purpose. The important design constraint is that execution is not exposed before purpose.

Cross-language verification​

The acceptance work removed obsolete Python and .NET two-argument forms and added required-resource resolution to generated runtimes. Tests cover successful injection, missing-resource failure and rejection of the old call shape. Freshly generated workspaces compile and execute with their formal runtimes.

This is an API-design control, not merely a runtime if statement: make the unsafe call difficult or impossible to express.

They do not answer a different data-access question: was this property loaded at all?

For a partially selected entity, string? Name == null can mean either SQL NULL or “the query never selected Name.” TeaQL's generated .NET E expressions model those as separate states and preserve the distinction through ADO.NET mapping.

Why Nullable Types Are Necessary but Insufficient​

Suppose a task name is optional:

string? name = E.Task(task).Name().Eval();

If the query selected name and the database returned NULL, Eval() should return null. If the query selected only id, the same return value would hide an incomplete query.

The generated contract is:

HasValue also throws for NotLoaded. It cannot be used to turn a query error into ordinary absence.

The ADO.NET Boundary Matters​

Many row mappers contain logic like this:

if (!reader.IsDBNull(index))
    record[reader.GetName(index)] = ConvertValue(reader.GetValue(index));

That code destroys the distinction before the entity exists. A selected NULL column disappears from the record and becomes indistinguishable from an unselected column.

TeaQL now keeps the key and records an explicit null value:

record[reader.GetName(index)] = reader.IsDBNull(index)
    ? new Value.NullValue()
    : FromDbValue(reader.GetValue(index));

The generated model then maps the record while retaining its keys:

Task task = Task.FromRecord(record);

if (!task.IsLoaded("Name"))
    throw new Exception("Name should have been part of the projection");

string? name = E.Task(task).Name().Eval();

FromRecord assigns non-null values and marks every returned column as loaded, including Value.NullValue.

Typed Query APIs for E Evaluation​

Generated requests expose raw records for aggregation and low-level work, and typed entity methods for load-aware evaluation:

var tasks = await Q.Tasks()
    .WithNameIs("Hello")
    .Comment("Read the task for display")
    .Purpose("Render the task detail page")
    .ExecuteEntitiesForListAsync(ctx, service);

var name = E.Task(tasks[0]).Name().Eval();

The corresponding single-result method is ExecuteEntityForOneAsync.

These APIs make the mapping choice explicit. A caller that wants dictionaries can keep using ExecuteForListAsync; a caller that wants generated E expressions can request load-aware models.

Fallback Is Not an Error Handler​

The following code uses a valid business default only when Name was loaded and absent:

string label = E.Task(task).Name().OrElse("Unnamed");

For an unselected Name, OrElse propagates TeaQLNotLoadedException. The exception includes Root, AccessPath, BreakPoint, and SuggestedFix:

try
{
    E.Task(Task.Refer(99)).Name().OrElse("Unnamed");
}
catch (TeaQLNotLoadedException error)
{
    Console.WriteLine(error.AccessPath);   // Name
    Console.WriteLine(error.SuggestedFix); // SelectName(...)
}

This turns a silent default into an actionable test failure.

Real SQLite Verification​

The generated .NET SQLite integration test creates and saves a task graph, updates a selected column to SQL NULL through ADO.NET, reloads it with a typed request, and verifies all three conditions:

typedLog.IsLoaded("Detail") == true
E.TaskExecutionLog(typedLog).Detail().Eval() == null

The same test also verifies schema creation, graph persistence, reconnect and query, update, optimistic version increment, and direct database reads.

At the generator level, the full regression finished with 109 tests, zero failures, and zero errors. Tests requiring unavailable connection variables were reported as conditional skips rather than successes.

Clear Failures Are an AI Feature​

A coding agent faced with a late NullReferenceException must infer whether the problem is bad data, a nullable field, mapping code, or a missing selection.

A TeaQLNotLoadedException reduces the repair to a bounded task: inspect the generated request, add the exact selection identified by the diagnostic, and rerun the test. The test then permanently verifies that the business expression has the data it requires.

Nullable annotations describe the domain. Load state describes the query. A robust data runtime needs both.

We built the same read model with TeaQL Rust and conventional Rust plus SQLite. The first comparison was wrong in three important ways. Correcting those errors made the result more useful than the original benchmark.

The Page We Measured​

The page is an order management center with the following backend behavior:

• dynamically filter orders using fields selected at runtime;
• support root fields, parent-relation paths, and child-relation paths;
• return a stable paginated order list and the complete matching count;
• calculate four status facets from the same active filter;
• include order number, order date, status, and product previews;
• include the complete line-item count for a +N more UI;
• execute through a user context with an explicit business purpose;
• leave SQL, result, elapsed-time, user, and purpose evidence;
• return a typed native result rather than assembling unvalidated JSON.

Both implementations used the same deterministic SQLite fixture. The verified dataset contains 60 orders, evenly distributed across four statuses.

Why the First Comparison Was Wrong​

Benchmarks become persuasive by removing advantages, not by adding them. We changed the comparison three times after reviewing its assumptions.

Correction 1: Conventional JSON Is Not a Production Result​

The first conventional implementation created serde_json::Value objects inside SQLite row callbacks. It was executable, but it had no strong result types, status enum, repository boundary, checked conversions, or structured error model.

That understated the conventional implementation. We replaced it with a strong OrderPage result containing typed rows, product previews, status facets, dates, counts, and validation. We also added a repository boundary, request context, purpose-aware SQL evidence, result summaries, and elapsed time.

Correction 2: The Domain Model Is Not a Page Cost​

TeaQL's 74-line model is excluded from the comparison.

That model is not disposable code written only for this page. Without TeaQL, the same domain still needs to be described in requirements, an ER model, schemas, API documentation, entities, or another durable specification. With TeaQL, the model is also reused to generate APIs, documentation, runtime metadata, and implementations in multiple languages.

Charging the whole model to one TeaQL page would count a reusable architectural asset as a one-off feature cost.

Correction 3: TeaQL Does Not Need a Handwritten Presenter​

We initially wrote a 96-line Presenter that converted generated TeaQL entities into the conventional OrderPage shape. That made byte-for-byte response comparison easy, but it forced TeaQL to pay for an abstraction required only by the conventional implementation.

The TeaQL runtime already serializes a generated SmartList<T> directly:

let page = load_order_page(&ctx, &request).await?;
let response = WebResponse::from_smart_list(page);

The Presenter was deleted. TeaQL now returns its native generated entity graph, record count, dynamic aggregates, and facets. Conventional Rust returns its handwritten strong OrderPage.

The two native wire shapes are intentionally allowed to differ. A test-only jq normalizer extracts the business fields needed for semantic parity. That normalizer is evidence tooling, not application code, and is excluded from both sides.

This correction also changed the contract accounting. Only the 79-line input request contract is shared and excluded. The 100-line conventional result contract is now counted only on the conventional side.

The TeaQL Query​

The measured TeaQL data-access implementation is 31 nonblank handwritten lines:

fn line_items_for_present() -> OrderLineRequest {
    Q::order_lines_minimal()
        .comment("Select product previews for each order")
        .select_product_name()
        .select_image_url()
}

fn order_statuses_for_facet() -> OrderStatusRequest {
    Q::order_statuses_minimal()
        .select_name()
        .select_code()
        .count_customer_orders()
}

pub async fn load_order_page(
    ctx: &ServiceRuntime,
    request: &OrderPageRequest,
) -> Result<SmartList<CustomerOrder>, Box<dyn std::error::Error>> {
    let filter_json = serde_json::to_string(request.filter())?;
    Ok(Q::customer_orders_minimal()
        .comment("Load the searchable order management page")
        .select_order_number()
        .select_order_date()
        .select_status_with(
            Q::order_statuses_minimal().select_name().select_code()
        )
        .filter_with_json(&filter_json)
        .facet_by_status_as("order_status", order_statuses_for_facet())
        .select_order_line_list_with(line_items_for_present())
        .count_order_lines()
        .order_by_order_number_asc()
        .purpose("Render the order management center")
        .execute_for_page(ctx, request.offset(), request.limit())
        .await?)
}

This is not a string wrapper around one SQL statement. It asks for a typed domain result with a relation, relation aggregate, total count, facet, dynamic filter, stable order, paging, trace comments, and an execution purpose.

Composition Is the Feature​

Extracting order_statuses_for_facet() is more than a cosmetic refactor. The function returns an OrderStatusRequest: a typed query value that can be passed into the outer CustomerOrderRequest.

fn order_statuses_for_facet() -> OrderStatusRequest {
    Q::order_statuses_minimal()
        .select_name()
        .select_code()
        .count_customer_orders()
}

Q::customer_orders_minimal()
    .facet_by_status_as("order_status", order_statuses_for_facet())

The same pattern composes the product-preview request into the order request:

.select_order_line_list_with(line_items_for_present())

This is a structural difference from ordinary handwritten SQL. SQL itself has subqueries and CTEs, but application-level SQL fragments are usually not closed under composition: two fragments can each be valid and still become invalid or semantically wrong when concatenated. They may introduce a second WHERE, reuse an alias or parameter position, change grouping, apply pagination at the wrong level, or cause the list, count, and facet paths to disagree.

Conventional code can build a composable query AST to solve this problem, but then the application or framework must provide typed nodes, relation metadata, alias management, parameter binding, aggregate semantics, and a SQL compiler. TeaQL generates that infrastructure from the domain model. The handwritten unit of reuse is therefore a domain query—not a string fragment—and invalid combinations are constrained by generated method signatures and the Rust type checker before SQL is produced.

That is why naming a subquery as a function works so naturally here. The function can be read, tested, reused, and nested without exposing SQL assembly details to the page query.

Dynamic Search Is the Expensive Part​

The verified input may choose any subset of six representative fields:

For example:

{
  "order_date": "2024-01-2",
  "status.code": "PEND",
  "order_line_list.product_name": "Box"
}

The generated TeaQL request layer resolves those paths from the domain model. The query above does not change when the caller selects A, B, C, or A+B+C.

The conventional fixed-whitelist implementation must explicitly repeat the mapping in the list, count, and facet queries:

AND (?1 IS NULL OR o.order_number LIKE ?1)
AND (?2 IS NULL OR o.order_date LIKE ?2)
AND (?3 IS NULL OR s.code LIKE ?3)
AND (?4 IS NULL OR s.name LIKE ?4)
AND (?5 IS NULL OR EXISTS (
    SELECT 1 FROM customer_data c
    WHERE c.id = o.customer
      AND c.version > 0
      AND c.name LIKE ?5))
AND (?6 IS NULL OR EXISTS (
    SELECT 1 FROM order_line_data f
    WHERE f.customer_order = o.id
      AND f.version > 0
      AND f.product_name LIKE ?6))

It must also keep parameter positions and typed values aligned across all three statements.

There is another legitimate conventional design: build a generic search AST, field registry, relation-path resolver, operator parser, type converter, and SQL compiler. That avoids repeated fixed SQL, but it is no longer a small page implementation. It is the beginning of model-driven query infrastructure.

What Was Executed​

The acceptance harness ran seven scenarios:

Each semantic comparison covered rows, total count, line-item count, product preview data, remaining count, and all four status facets.

The harness also proved that:

• both typed input boundaries reject unknown fields;
• omitting TeaQL .purpose(...) causes a Rust compile error before execution;
• the standard TeaQL log buffer records user, purpose, nested trace, SQL, result summary, and elapsed time without feature-specific log statements;
• the verified TeaQL trace contains no product-master N+1 query.

TeaQL emitted seven SQL statements while the conventional implementation emitted three. That is runtime evidence, not a performance score. The benchmark does not claim that more or fewer statements alone predict latency, throughput, or database cost.

LOC Is Only Half the Review Cost​

There is a second difference that a line-count table does not show: how many places a reviewer must keep in working memory.

To review the business behavior of the TeaQL page, the reviewer opens one file: query.rs. That file shows, in one continuous expression:

• which order fields are selected;
• how status and line-item relations are projected;
• where the dynamic filter enters;
• how status facets and line-item counts are calculated;
• how results are ordered and paginated;
• the trace comments and the business purpose of execution.

The generated model vocabulary, dynamic path resolution, typed result graph, SQL generation, serialization, context propagation, and standard evidence do not need to be reconstructed from page-specific glue code. The executable demo also has a 25-line generic entry point, but it does not contain the page's business query. For a change-focused review, the business review surface is one file.

The conventional implementation is properly separated into layers, but a complete feature review crosses five handwritten files:

This is not an argument against separation of concerns. Those separations are necessary when the infrastructure is handwritten. It is an argument about review fan-out: TeaQL keeps the page-specific decision in one declarative query while generated and standard infrastructure carries the cross-cutting concerns. Conventional Rust makes those responsibilities explicit in application code, so the reviewer has to follow them across files and keep the connections consistent.

For coding agents, this locality matters as much as raw LOC. A smaller diff is useful; a diff whose meaning can be established from one file is easier to generate, inspect, and revise.

The Final Review-Surface Numbers​

The primary comparison counts the handwritten data-access implementation:

The secondary comparison counts all handwritten runtime code used by the executable benchmark:

That is 61 versus 443 nonblank handwritten lines, an 86.2% reduction in this specific executable benchmark.

The following are excluded:

• the reusable domain model;
• the shared input request contract;
• generated TeaQL code;
• fixture generation;
• evidence exporters and semantic normalizers;
• dependencies and build output;
• blank lines and line comments.

A Real Limitation the Benchmark Found—and the Fix It Drove​

The benchmark exposed a correctness gap in TeaQL Rust 4.2.5: applying .limit(3) to a nested relation limited the child query globally, rather than selecting three children independently for every parent order.

That means the aesthetically ideal query:

Q::order_lines_minimal()
    .limit(3)
    .select_product_name()
    .select_image_url()

did not implement a per-order product preview correctly in the runtime used for the original run. Keeping it in the benchmark would have made the TeaQL code shorter but the result wrong, so the verified query did not use that limit.

Instead, the Rust response loads the order-line snapshots for the current page. The test/UI projection consumes the first three children of each order while the generated relation aggregate retains the complete line-item count. This preserves the required response semantics, but it is bounded over-fetch—not the ideal database execution plan.

A separate Java 1.526 probe generated the expected per-parent Top-N SQL using ROW_NUMBER() OVER (PARTITION BY customer_order ...). That probe also found a different gap: its generated child-count value was not attached to the returned parent entity.

The follow-up fix was implemented on 2026-08-12 against the TeaQL Rust v4.2.7 codebase. A paged relation request now carries its reverse foreign key as a partition key. The SQL compiler emits ROW_NUMBER() OVER (PARTITION BY ...), applies offset and limit to each partition, and the runtime removes the internal rank column before attaching children to their parents. The regression suite checks two parents with three selected children each; a real in-memory SQLite execution starts with five children for each parent and returns exactly six rows, the top three per parent. The remote v4.2.7 run passed 171 Rust tests across core, SQL, runtime, and the SQLite provider.

The Java child-count attachment path was fixed in the same follow-up. Its portable SQL runtime now maps grouped aggregate rows back to the returned parent entities, including a zero default when a parent has no matching child. The remote Java reactor run passed 236 tests with no failures or errors.

These fixes close the two concrete parity gaps found by the probes. The original benchmark evidence still records the behavior of the released runtime it actually tested; its bounded-over-fetch implementation should remain in that historical run until the complete benchmark is rerun against a release that contains the Rust fix.

We publish this because a benchmark should be allowed to find defects in the technology it evaluates. The limitation does not change the seven verified semantic comparisons, dynamic-filter checks, purpose compile gate, trace evidence, or review-surface measurement. It does narrow the performance claim: this benchmark proves the behavior of the page, but it does not claim that the Rust child-preview plan used in that original run was optimal.

What the Numbers Do—and Do Not—Mean​

This is not a universal claim that TeaQL is 83.5% shorter than every Rust data stack. A framework with comparable model metadata and a dynamic query engine may move much of the same work out of application code. That is precisely the architectural point: the reduction comes from reusable infrastructure, not from a clever spelling of SQL.

Handwritten SQL remains the right choice for one-off reporting, database-specific optimization, or carefully tuned critical paths. The question is whether every ordinary business page should manually rebuild field mapping, relation search, counts, facets, typed assembly, context, and evidence.

Finally, fewer reviewed lines suggest fewer opportunities for coding-agent drift and lower human review effort, but LOC is not a direct Token measurement. We have not yet measured end-to-end model Token savings, so we do not convert the LOC percentages into Token claims.

Why This Matters for Coding Agents​

A coding agent can generate 443 lines. The harder problem is keeping those lines coherent when requirements change:

• a new searchable relationship is added;
• a field changes type or name;
• the list, count, and facet filters must remain identical;
• user and purpose context must survive every execution path;
• the response must remain typed and reviewable.

TeaQL moves that repeated structure into a generated domain vocabulary and a runtime query engine. The handwritten code stays close to the product manager's language: orders, status, product previews, counts, filters, purpose, and page.

That is the more important result. The agent writes less code, but reviewers also inspect code expressed in the same domain model used by the rest of the system.

Source and Related Reading​

• Order read-model benchmark source
• Dynamic JSON Query cookbook
• Generated Query APIs vs Handwritten SQL
• TeaQL vs MyBatis: an order page example

The verified run recorded in the benchmark is named-status-facet-verified-20260812. The evidence bundle contains native responses, normalized semantic responses, parity diffs, SQL traces, the missing-purpose compiler error, LOC measurement, and SHA-256 hashes.

value, ok := lookup(key)

That shape is useful for an E expression too, but one boolean cannot explain why a value is absent. In data-access code, there is a critical difference between a loaded null-like value and a field the query never selected.

TeaQL's generated Go E expressions preserve three states and provide two evaluation styles: TryEval() for explicit error handling and Eval() for strict fail-fast business logic.

When present == false Is Not Enough​

This looks reasonable:

name, present := E.Task(task).Name().Eval()
if !present {
    name = "Unnamed"
}

It is correct when name was loaded and legitimately absent. It is wrong when the task came from an ID-only projection. In the latter case, the fallback fabricates a business value from missing evidence.

TeaQL treats these cases differently:

The strict Eval() method has the familiar two-result shape, but panics if the third state is NotLoaded.

Explicit Handling with TryEval​

At an application boundary, callers can inspect the error directly:

name, present, err := E.Task(task).Name().TryEval()
if err != nil {
    var notLoaded TeaQLNotLoadedError
    if errors.As(err, &notLoaded) {
        return fmt.Errorf(
            "query did not load %s at %s: %w",
            notLoaded.BreakPoint,
            notLoaded.AccessPath,
            err,
        )
    }
    return err
}
if !present {
    name = "Unnamed"
}

Inside invariant-heavy business logic, Eval() is intentionally stricter:

name, present := E.Task(task).Name().Eval()

If Name was not loaded, the panic contains the root entity, access path, breakpoint, suggested selection, and a human-readable explanation.

Fallback Does Not Hide a Query Bug​

The generated OrElse operation first performs strict evaluation:

label := E.Task(task).Name().OrElse("Unnamed")

It returns the fallback only for a legitimate missing value. If the field was not loaded, the same structured error propagates. This rule prevents a common failure mode in which defensive code makes an incomplete query appear valid.

Load State Comes from Records​

Generated Go entities record which keys were present when FromRecord mapped a database or transport record:

task := task.NewTask()
if err := task.FromRecord(record); err != nil {
    return err
}

A key present with a null-like database value is loaded. A key absent from the record is NotLoaded. New entities are fully available for ordinary construction, while MarkLoadedOnly supports precise partial-entity tests:

partial := task.NewTask().UpdateId(99).MarkLoadedOnly("id")

_, _, err := E.Task(partial).Name().TryEval()
if err == nil {
    t.Fatal("expected an unloaded-field error")
}

The same state is propagated through foreign-key ID accessors and generated reverse-list expressions such as Size, First, and Get.

A Better Failure for Humans and AI Agents​

A generic panic such as interface conversion: interface {} is nil provides almost no repair guidance. TeaQLNotLoadedError is a query-contract diagnostic:

TeaQLNotLoadedError:
  root=Task(id=99)
  access_path=name
  break_point=name
  suggested_fix=SelectName(...)

That structure matters during test-driven development. A developer immediately knows which request to review. An AI coding agent can read the generated request source, add the exact selection, and rerun the failing test without guessing a method name.

Verification​

The generated Go workspace was compiled and executed against the TeaQL Go runtime used by the integration environment. Tests covered scalar evaluation, foreign-key IDs, reverse-list traversal, TryEval, strict panic behavior, and the rule that OrElse cannot hide NotLoaded.

The complete code-generator regression finished with 109 tests, zero failures, and zero errors. Conditional tests that require additional database connection variables remained skipped rather than being counted as passes.

Go's preference for explicit errors fits this design well. The important part is not whether an application chooses TryEval or strict Eval; it is that the runtime never collapses “we do not know” into “the value is empty.”

Does null mean the database value is NULL, or does it mean the query never loaded the property?

Those two states have completely different business meanings. Treating both as null can make a test pass and let the wrong decision reach production.

TeaQL's generated Java E expressions now preserve three states: Value, Null, and NotLoaded. A missing preload becomes a structured exception at the point of use, while a genuine SQL NULL remains a legitimate null value.

The Bug That Ordinary Null Safety Cannot See​

Consider a task query that selects only id, followed by business logic that reads name:

Task partial = Task.refer(99L);
String displayName = E.task(partial).getName().orElse("Unnamed");

Returning "Unnamed" would look null-safe, but it would hide a query bug. The application does not know that the name is absent; it never asked the database for the name.

The generated E expression instead throws E.TeaQLNotLoadedException. Even the fallback propagates the exception:

try {
    E.task(partial).getName().orElse("Unnamed");
    throw new AssertionError("NotLoaded was hidden");
} catch (E.TeaQLNotLoadedException error) {
    assertEquals("name", error.getAccessPath());
    assertEquals("name", error.getBreakPoint());
    assertEquals("selectName(...)", error.getSuggestedFix());
}

This behavior is intentional. A default is appropriate for a loaded null, not for missing evidence.

The Three-State Contract​

The generated entity tracks which properties were loaded. E expressions carry that state through scalar fields, to-one relations, and reverse lists.

The distinction survives database mapping. TeaQL checks whether the result row contains a column, not whether its value is non-null. A selected SQL NULL still invokes the generated entity mapper and marks the property as loaded.

Task loaded = /* loaded from a SELECT that includes name */;
assertNull(E.task(loaded).getName().eval());

That is a subtle but essential rule for partial projections and relation-heavy domain models.

A Diagnostic Designed for Tests and Coding Agents​

The exception includes machine-readable context:

TeaQLNotLoadedError:
  root=Task(id=99)
  access_path=name
  break_point=name
  suggested_fix=selectName(...)

For a deeper chain, the access path identifies the exact point where available data ends. A developer can act on this immediately. An AI coding agent can do the same without guessing method names or reconstructing the query from an unrelated NullPointerException.

The resulting loop is short:

1. Generate the typed model and query APIs.
2. Run unit or integration tests.
3. Let the E expression fail at the first unloaded access.
4. Read the path and suggested preload.
5. Update the generated query chain and rerun the test.

The important shift is temporal: the bug becomes a test failure instead of a production data-quality incident.

Why This Is More Than Another Optional Wrapper​

Optional<T> can represent a value or absence. It cannot, by itself, explain whether absence is legitimate or caused by an incomplete query. Lazy-loading proxies can defer the question, but they introduce hidden I/O and can still fail after a session has closed.

E expressions make the query contract explicit. They do not issue a surprise query. They either evaluate already-loaded data, return a legitimate null, or identify the missing preload.

Verification Evidence​

This behavior was tested in the generated Java code and in the Java runtime:

• a reference entity fails on an unloaded scalar, including through fallback;
• PostgreSQL returns a genuine SQL NULL that evaluates as Null;
• the portable SQL runtime maps a selected SQLite NULL as loaded;
• the complete generator regression finished with 109 tests, zero failures, and zero errors; environment-dependent database cases remained conditional.

The PostgreSQL test ran against an isolated test container, and the portable mapping test used a real in-memory SQLite database.

An AI-Native Data Contract​

The goal is not to make every missing value fatal. The goal is to distinguish business absence from missing information.

Once that distinction is part of generated code, tests become much more powerful. They verify not only that a method returns the expected value, but also that the query loaded enough evidence to make the decision. And when the contract is violated, both humans and AI agents receive a precise repair path.