TeaQL Java

Sensitive log data

Runtime diagnostic logs redact payload values by default, before delivery to file, console, buffers, or custom logging sinks. Selecting a diagnostic sink alone does not authorize plaintext. For controlled troubleshooting only:

export TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS=I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK

Only this exact value enables plaintext permission; empty values, true, and whitespace variants do not. Enabling it emits a warning. Credential-classified fields remain redacted. The flag does not force every sink to expose values. SQL without reliable field/literal provenance may be suppressed and marked NOT REPLAYABLE. Execution parameters and persisted business data are unchanged.

Do not put sensitive data in free-text comments or purpose declarations. TeaQL cannot govern arbitrary application prints or independent driver loggers; configure those separately. This setting does not erase older plaintext files. Restrict access and retention when using plaintext diagnostics, then unset the variable and restart processes when troubleshooting is complete.

TeaQL Java is the Java runtime for TeaQL domain applications. It provides a typed entity and request model, auditable execution, pluggable runtime capabilities, portable SQL support, database dialects, and integrations for server-side Java and Android.

TeaQL is designed for applications in which code may be written or operated by both humans and coding agents. Instead of exposing unrestricted infrastructure operations, the runtime keeps execution behind explicit context, intent, policy, and capability boundaries.

Recommended Agent Harness

When building database-backed applications with the TeaQL Java runtime, we recommend using it together with the TeaQL Agent Kit. The Agent Kit is TeaQL's continuously evolving Harness Engineering method. It gives coding agents a model-mediated, executable workflow for domain modeling, deterministic evaluation and repair, code generation, implementation, and evidence-based verification as the generator and runtimes evolve.

Why TeaQL?

TeaQL applies five safeguards to application operations:

1. Context-bound execution — reads and writes run through a UserContext, which carries identity, trace, and runtime capabilities.
2. Declared intent — reads require .comment(...).purpose(...); writes use .auditAs(...) before an execution terminal becomes available.
3. Policy gates — QueryPolicy reviews reads; MutationPolicy reviews one immutable graph-level MutationPlan before the first provider write.
4. Explicit capabilities — optional operations such as HTTP tools, dynamic fields, and business ID generation are supplied through dedicated modules and registered runtime capabilities.
5. Typed graph mutation — applications persist typed entity graphs instead of assembling ad hoc update statements and relationship loops.

The runtime also records execution metadata through a pluggable RuntimeLogSink, allowing applications to choose their own audit and logging backend.

Quick Start

Requirements

• Java 17 or later
• Maven 3.8 or later

Spring Boot

Spring Boot applications can use the compatibility starter. Keep the TeaQL version in one property so all TeaQL artifacts stay aligned:

<properties>
    <teaql.version>1.526-RELEASE</teaql.version>
</properties>

<dependencies>
    <dependency>
        <groupId>io.teaql</groupId>
        <artifactId>teaql-spring-boot-starter</artifactId>
        <version>${teaql.version}</version>
    </dependency>
</dependencies>

The project was renamed from teaql-spring-boot-starter to teaql-java when it grew from a Spring-only package into a modular Java runtime. The starter artifact name is retained for compatibility.

Runtime Usage

A generated TeaQL request becomes executable after its purpose is declared:

SmartList<Task> tasks = Q.tasks()
    .comment("Load tasks")
    .purpose("Display the kanban board")
    .executeForList(userContext);

Mutations declare an audit action:

task.auditAs("Move task to Done").save(userContext);

Applications can replace runtime services such as QueryPolicy, the MutationPolicyRegistry, MutationPolicyApprovalProvider, RuntimeLogSink, DataServiceRegistry, InternalIdGenerationService, and EntityMetaFactory in their integration layer.

Query and Mutation execution logs are enabled by default. The built-in default sink is safe for ordinary operator output: it includes intent, trace, elapsed time, outcome, and parameterized SQL, but excludes bind values and rendered Debug SQL. Enable copy/paste SQL only for a controlled troubleshooting surface:

TeaQLRuntime runtime = TeaQLRuntime.builder()
    .metadata(metadata)
    .queryExecutionLogging(true)
    .mutationExecutionLogging(true)
    .diagnosticSqlLogging(true) // values and Debug SQL; apply restricted retention
    .build();

The Query and Mutation switches remain independent. Selecting diagnostic SQL changes the built-in destination; it does not enable or disable either family. Custom RuntimeLogSink implementations receive only parameterized SQL unless they explicitly override requiresSensitiveSqlData() to return true. Custom UserContext implementations must also explicitly delegate or override requiresSensitiveSqlLogData() when they enable a diagnostic sink. The optional file-backed LogManager requests value-bearing SQL only with TEAQL_SQL_LOG=_full_with_payload; restrict access and retention before enabling it.

Security Foundations

TeaQL Java is a server-side security reference runtime:

• ordinary Query and Mutation logs are enabled by default and retain intent, trace, parameterized SQL, timing, and outcome without bind values;
• copy/paste SQL and parameter values require an explicitly selected sensitive diagnostic sink;
• the TFP endpoint applies trusted server policy, bounded queries, writable-field rules, tenant scope, and optimistic version in the provider operation;
• boundary-facing entity references can be issued and verified through UserContext without serializing raw internal ID/version pairs.

Install an application-owned key provider at the runtime boundary:

byte[] activeKey = loadThirtyTwoByteKeyFromSecretManager();
var provider = AeadRoundTripReferenceProvider.fromProcessEnvironment(
    DeploymentProfile.PRODUCTION,
    "order-service",
    "production",
    new StaticRoundTripReferenceKeyProvider(
        new RoundTripReferenceKey("k2", activeKey)),
    currentAuthorizationPolicy);
var runtime = TeaQLRuntime.builder()
    .roundTripReferenceProvider(provider)
    .build();
userContext.withTrustedReferencePrincipal(
    new TrustedReferencePrincipal("oidc", "alice", "Platform", 7));
var scope = new ReferenceDocumentScope(
    "order-editor-100", "edit-order", "Order", 100, 9);

Object wire = userContext.referenceFor(orderItem, scope, Duration.ofMinutes(15));
ResolvedRoundTripReference resolved = userContext.resolveReference(
    wire, scope, "OrderItem");

The tqr1 token uses AES-256-GCM with HKDF-SHA-256, carries a key ID for rotation, expires, and binds Actor, Domain Root, service, environment, purpose, document, Aggregate identity/revision, entity type/ID/version. Current authorization runs both when issuing and consuming the reference. Java and Rust retain the same deterministic golden vector.

For local diagnosis only, the exact TEAQL_UNSAFE_EXPOSE_RAW_ENTITY_IDS=I_UNDERSTAND_THIS_EXPOSES_INTERNAL_ENTITY_IDS_FOR_LOCAL_DEBUGGING_ONLY acknowledgement changes the startup-selected wire shape to {id, version} in development/test. Production fails closed; raw mode does not bypass current authorization, type, version, projection, Checker/Fix, audit, or Mutation Ledger enforcement. See the canonical context-bound reference contract.

Choose Modules

Most applications need the core runtime, one data-access path, and one database dialect. Add optional integrations only when the application uses them.

Application	Typical modules
Spring Boot with JDBC	Compatibility starter, Spring JDBC provider, and one database dialect
Plain JVM, Quarkus, or Micronaut with JDBC	teaql-runtime, teaql-data-service-sql, teaql-provider-jdbc, and one database dialect
Android or a portable SQL client	teaql-android or teaql-sql-portable, plus a platform-specific TeaQLDatabase implementation
In-memory execution	teaql-runtime

Runtime and API

Module	Purpose
teaql-core	Entities, requests, criteria, metadata, policies, audit contracts, and runtime interfaces
teaql-runtime	Default runtime and concurrent in-memory execution service
teaql-jackson	Explicit TeaQL entity serialization and deserialization
teaql-query-json	JSON-to-request query parsing
teaql-runtime-log	Optional file/stdout runtime logging backend

SQL and Providers

Module	Purpose
teaql-data-service-sql	SQL data-service executor and adapter contracts
teaql-provider-jdbc	Direct JDBC execution adapter
teaql-provider-spring-jdbc	Spring JDBC execution adapter
teaql-sql-portable	SQL repository path through the TeaQLDatabase abstraction, without spring-jdbc

Supported dialect modules are teaql-sqlite, teaql-mysql, teaql-postgres, teaql-oracle, teaql-db2, teaql-mssql, teaql-hana, teaql-duckdb, teaql-snowflake, and teaql-dm8. In normal applications, select only the dialect for the target database.

Optional Capabilities and Utilities

Module	Purpose
teaql-dynamic-fields-api	Dynamic-field API and in-memory implementation
teaql-dynamic-fields-jdbc	JDBC persistence for dynamic-field definitions and values
teaql-business-id-jdbc	JDBC-backed business ID generation
teaql-context-runtime-tools	Runtime tool registration and policy integration
teaql-tool-http	Auditable HTTP tool capability
teaql-android	Android integration helpers
teaql-utils, teaql-utils-json	Framework-neutral utility abstractions
teaql-utils-reflection, teaql-utils-spring	Optional reflection- and Spring-backed utility implementations

For business IDs, use the context-owned BusinessIdService and explicit context.ensureSchema() lifecycle. The focused runtime example documents the preferred contract and the deprecated legacy boundary.

Framework Notes

Spring Boot and SQLite

teaql-autoconfigure provides the default Spring Boot runtime beans, while the compatibility starter pulls that auto-configuration into an application.

SQLite applications can use standard Spring datasource properties:

spring.datasource.url=jdbc:sqlite:./data/app.db
spring.datasource.driver-class-name=org.sqlite.JDBC

Android

teaql-sql-portable keeps spring-jdbc out of the repository path. Android applications provide an Android-backed TeaQLDatabase implementation, and TeaQL executes positional SQL through that abstraction. See the Android integration guide.

Native Image and Reflection

The main entity construction, JSON, and SQL row-mapping paths are designed to avoid reflection-heavy bean mutation:

• teaql-jackson registers explicit entity serializers and deserializers through TeaQLModule.
• teaql-sql-portable creates entities through EntityDescriptor.createEntity().
• Generated or hand-written metadata registers an entitySupplier, such as Task::new, beside its targetType.

Dynamic and additional values should remain JSON-friendly: scalars, maps, lists, or other explicitly serializable values. Arbitrary application objects may still trigger Jackson's default bean introspection.

See the Native Image Reflection Guide for the baseline and coding rules.

Build and Test

git clone https://github.com/teaql/teaql-java.git
cd teaql-java
mvn clean install

Useful verification commands:

mvn test
mvn spotbugs:check

The PostgreSQL/MySQL integration tests are optional during an ordinary local build, but the Live SQL dialects CI workflow requires both databases and fails instead of counting a skipped connection as a pass. Run them locally against dedicated, freshly created teaql_live_* databases (never a shared application database):

export TEAQL_REQUIRE_LIVE_DB=true
export TEAQL_TEST_POSTGRES_URL=jdbc:postgresql://127.0.0.1:5432/teaql_live_local
export TEAQL_TEST_POSTGRES_USER=<test-user>
export TEAQL_TEST_POSTGRES_PASSWORD=<test-password>
export TEAQL_TEST_MYSQL_URL='jdbc:mysql://127.0.0.1:3306/teaql_live_local?serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=true'
export TEAQL_TEST_MYSQL_USER=<test-user>
export TEAQL_TEST_MYSQL_PASSWORD=<test-password>
mvn -pl teaql-postgres,teaql-mysql -am \
  -Dtest=PostgresIntegrationTest,MysqlIntegrationTest \
  -Dsurefire.failIfNoSpecifiedTests=false test

The tests create task_data, context_probe_data, and teaql_id_space within those isolated databases. In addition to schema and CRUD behavior, each dialect uses the production IdSpaceIdGenerator for entity saves and verifies 40 contended allocations across four independent generator instances followed by restart continuity. Dispose of the databases after the run.

Documentation

• Runtime design
• Runtime logging design
• Native image reflection guide
• Database dialect integration guide
• Dynamic Fields API
• Dynamic Fields JDBC
• Changelog

Contributing and Support

See CONTRIBUTING.md for contribution requirements and CODE_OF_CONDUCT.md for community guidelines.

Report defects and enhancement requests through GitHub Issues. Include the TeaQL version, Java version, framework and database details, and reproduction steps. For vulnerabilities, follow the private reporting process in SECURITY.md.

TeaQL Java is licensed under the Apache License 2.0.