TeaQL Glossary

This is the canonical public vocabulary for TeaQL documentation, generated code, runtime APIs, and AI coding agents. Use these terms consistently instead of translating them into familiar ORM terminology.

For machine-readable forms, use /glossary.md or /glossary.json. AI tools can discover both through /llms.txt.

Context and Runtime

Context (UserContext)

The trusted execution context supplied to one business operation. It carries data-service access, identity, tenant, request policy, audit facilities, telemetry correlation, and other initialized resources.

• Required parameter name: context
• Used by: create, save, query, page, count, stream, tool, and federation operations
• Not: the process-level runtime or a raw database connection
• Forbidden parameter aliases: runtime, ctx, service, dataService

let schools = Q::schools()
    .comment("List active schools")
    .purpose("Build the operations dashboard")
    .execute_for_list(context)
    .await?;

Runtime

The process- or application-level owner of infrastructure and long-lived resources. A runtime may own providers, pools, installed modules, and the factory used to create request contexts.

• Used for: application startup, provider/pool ownership, module installation, and context creation
• Not: the argument passed to save or query execution

Runtime Module

A passive, composable manifest of entity metadata and runtime capabilities. Installing a module registers capabilities; it does not modify a database. Schema changes require a separate, explicit ensureSchema(module) call.

Model and Generated API

KSML

TeaQL's model source of truth. The generator derives entities, requests, expressions, workspaces, and Assist guidance from KSML. See KSML Vocabulary for modeling-specific terms.

Entity

A generated, typed representation of a business object. An entity also tracks field load state, changes, identity, optimistic version, relations, and audit intent; it is not merely a database row DTO.

Request

A generated, typed query builder for one entity. A request accumulates filters, projection, relations, ordering, paging, comment, and purpose before execution.

Q

The generated entry point for entity requests and new-entity creation. Use Q instead of constructing query objects or guessing plural names by hand.

E (Expression)

The generated typed expression entry point. E evaluates fields, relations, and derived expressions while preserving TeaQL load-state semantics.

SmartList

TeaQL's extensible typed collection returned by list operations. It can carry result metadata such as totals and facets. Do not replace it with a language's raw list type in the shared API contract.

Workspace

A generated project assembly target, such as a core library, console application, web service, or mobile application. A workspace owns build and runtime wiring around generated domain code.

Entity State and Persistence

Loaded

The field was included in the authoritative materialized record. Its value may be non-null or null.

Null

The field was loaded and its authoritative value is null. Null is data, not an indication that the field was omitted.

Not Loaded

The field was not materialized. Reading it as if it were loaded is an error. Not Loaded must not collapse into null, None, Optional.empty, or a language default value.

Authoritative Save Result

The strongly typed entity returned after persistence, including generated IDs, the new optimistic version, database defaults, and correct Loaded/Null/Not Loaded state. A mutation count or generated-ID dictionary alone is not the TeaQL save contract.

Optimistic Version

The persisted entity version used to detect stale updates or deletes. A successful mutation returns the authoritative next version.

Intent, Audit, and Governance

Comment

A human-readable description of what a query is doing. Comment is operational and diagnostic context; it does not replace Purpose.

Purpose

The business reason authorizing and explaining query execution. Calling Purpose moves a generated request into its executable stage.

Audit / auditAs

The explicit business reason attached to a mutation before save. Audit intent is part of the mutation contract, not an optional source-code comment.

Request Policy

Trusted runtime policy that constrains an operation, including tenant, permission, paging, and governance rules. It is initialized in Context and must not be accepted from untrusted query JSON or federation payloads.

Integration and AI-Native Engineering

Data Service

The provider-neutral capability used by TeaQL to execute queries and mutations. Concrete SQL, memory, or remote providers are accessed through the Context rather than passed as extra operation parameters.

Provider

A concrete implementation of a runtime capability, such as SQLite, PostgreSQL, Redis, or an S3-compatible object store. Provider-specific behavior must not silently change the common TeaQL contract.

TeaQL Federal Protocol (TFP)

TeaQL's provider-neutral cross-runtime protocol for typed query and audited mutation transport. Client and server endpoint support are separate capabilities.

RuntimeTelemetry

TeaQL's runtime-owned telemetry event boundary. OpenTelemetry is the standard adapter and OTLP is the portable export protocol; a telemetry backend is not part of the public TeaQL API.

Assist

Model-aware guidance generated from the same source as the application API. Assist tells a coding agent the exact create, update, delete, query, expression, debug, tool, and runtime-customization patterns available for the model.

Harness Engineering

The practice of surrounding AI-generated changes with model-aware generation, executable scenarios, environment evidence, failure diagnostics, and repeated verification. The TeaQL Agent Kit provides the recommended harness.

Conformance

Executable evidence that a capability has equivalent semantics in a named runtime/version and scenario. An API surface or third-party dependency alone does not constitute conformance.

Seven-Language Context Naming

Language	Canonical form
Java	UserContext context
Rust	context: &C or context: &UserContext
TypeScript	context: UserContext
Swift	context: UserContext
Python	context: UserContext or context
.NET	UserContext context
Go	context *runtime.UserContext

In Go, runtime is the package qualifier and context remains the parameter name. This does not violate the Context/Runtime distinction.

Maintenance Rule

When a public concept changes, update the structured glossary first, then the human page, generated Assist, examples, and executable conformance. New terms must state both what they mean and what commonly confused concept they do not mean.