# TeaQL Glossary for AI Coding Agents

Canonical HTML documentation: https://teaql.io/docs/reference/glossary

## Mandatory vocabulary

- **TeaQL Runtime**: reusable, domain-independent runtime platform for TeaQL's
  generated domain APIs and shared contracts. It currently has Java, Rust,
  TypeScript, Swift, Python, .NET, and Go implementations. Official repositories:
  [Java](https://github.com/teaql/teaql-java),
  [Rust](https://github.com/teaql/teaql-rs),
  [TypeScript](https://github.com/teaql/teaql-ts),
  [Swift](https://github.com/teaql/teaql-swift),
  [Python](https://github.com/teaql/teaql-python),
  [.NET](https://github.com/teaql/teaql-dotnet), and
  [Go](https://github.com/teaql/teaql-golang).
- **Context / UserContext**: trusted execution context for one business
  operation. Public parameter name: `context`. Never name this parameter
  `runtime`, `ctx`, `service`, or `dataService`.
- **Runtime**: process-level owner of providers, pools, installed modules, and
  context creation. Do not pass it to business operations as if it were a
  Context.
- **Runtime Module**: passive composable capability/metadata manifest.
  Installation does not modify a database; `ensureSchema(module)` is explicit.
- **Entity**: typed business object with identity, changes, relations,
  optimistic version, audit intent, and field load state.
- **Request**: generated typed query builder configured before execution.
- **Q**: generated request and new-entity entry point.
- **E / Expression**: generated typed expression entry point.
- **SmartList**: extensible typed TeaQL result collection; do not replace it
  with a raw language list in the shared contract.
- **Loaded**: field was materialized; value may be null or non-null.
- **Null**: field was loaded and its value is null.
- **Not Loaded**: field was not materialized; it is not null or a default value.
- **Authoritative Save Result**: persisted typed entity including generated ID,
  version, database defaults, and preserved load state.
- **Comment**: human-readable description of what a query does.
- **Purpose**: business reason for query execution and executable-stage gate.
- **Audit / auditAs**: explicit business reason required before mutation save.
- **Data Service**: provider-neutral query/mutation capability obtained through
  Context.
- **Provider**: concrete implementation such as SQLite or PostgreSQL.
- **TeaQL Federal Protocol (TFP)**: cross-runtime typed query and audited
  mutation protocol.
- **RuntimeTelemetry**: runtime telemetry boundary; OpenTelemetry is the
  standard adapter and OTLP the portable export protocol.
- **Assist**: model-aware exact API guidance generated with the domain API.
- **Harness Engineering**: model-aware generation plus executable verification,
  evidence, and diagnostics for AI-generated changes.
- **TeaQL Harness**: TeaQL's deterministic engineering system combining model
  evaluation, Assist, generation, generated workspaces, all seven TeaQL
  Runtimes, executable scenarios, Conformance, diagnostics, and retained
  evidence. Runtime is its execution and feedback layer; TeaQL Agent Kit is the
  recommended agent-facing implementation and entry point.
- **Conformance**: retained executable evidence for a named capability,
  runtime, version, and scenario.

## Context examples

Correct: `entity.save(context)` and `request.execute_for_list(context)`.

Incorrect: `entity.save(runtime)` and `request.execute_for_list(ctx)`.

Language forms: Java `UserContext context`; Rust `context: &C`; TypeScript and
Swift `context: UserContext`; Python `context`; .NET `UserContext context`; Go
`context *runtime.UserContext`.