How the TeaQL Harness Works

AI can produce software faster than people can review it. The difficult problem is therefore no longer only generating code. It is establishing which parts of a rapidly produced system are structurally valid, semantically consistent, executable, and supported by current evidence.

The TeaQL Harness places a deterministic engineering process around a probabilistic coding agent. This page distinguishes the current model/evaluate/generate/Assist/runtime workflow from proposed evidence and inference extensions; an architectural goal is not a claim that every runtime already implements it.

Business intent
    ↓
Inspectable domain model
    ↓
Evaluate ↔ repair
    ↓
Generated typed library and workspace
    ↓
Model-aware Assist ↔ implementation
    ↓
Compile, test, run, and retain evidence

The goal is not deterministic AI. The goal is deterministic structure around non-deterministic AI.

Why Prompt-to-Code Is Not Enough

A coding agent is effective at bounded tasks. It can implement a screen, endpoint, migration, or visual effect quickly. A large business system, however, is not merely a larger collection of small tasks. It needs shared semantics, cross-module invariants, privacy boundaries, compatible APIs, runtime policy, and evidence that remains tied to the versions that produced it.

Ten thousand doghouses do not become a skyscraper. A skyscraper also needs building codes, structural engineering, inspections, sequencing, and an evidence trail.

TeaQL therefore changes the primary object of review. Instead of asking people to inspect every generated line, the Harness helps them concentrate on:

• business intent and the semantic model;
• invariants, prohibited states, and authority boundaries;
• deterministic validation rules;
• failed checks, accepted exceptions, and residual judgment;
• executable evidence produced against identified versions.

Human review remains essential. It moves to the decisions where human judgment has the highest leverage.

1. Turn Intent into an Inspectable Model

The agent first expresses the requested business world as a KSML domain model. It does not invent persistence code, DTOs, schema migrations, and business services simultaneously.

Consider a regulated cross-border payment flow. The initial requirement may include:

• parties and organizations from several regions;
• signed KYB assertions whose source evidence must remain in-region;
• payment admission decisions;
• currencies, countries, and controlled status values;
• a multi-currency ledger and an audit trail.

The model becomes an intermediate representation that people and software can inspect before application code exists. It records vocabulary, objects, relationships, constants, identifiers, and supported sensitive-field metadata. Rich business-constraint inference is a separate experimental layer, not a prerequisite for today's core library.

2. Evaluate and Repair Until the Model Converges

An LLM-generated model is a candidate, not an accepted contract. The Evaluation Service applies deterministic rules and returns four result classes:

Result	Meaning
Error	A blocking defect. Generation must not proceed.
Warning	A material risk that must be repaired or explicitly accepted.
Suggestion	A non-blocking improvement that remains visible.
Solid	A deterministic check that the current model passed.

The important behavior is not a single pass or fail. It is observable convergence across repair rounds:

Round 1   7 Errors · 6 Warnings · 4 Suggestions · 31 Solids
Repair    Structure ✓

Round 2   1 Error  · 5 Warnings · 3 Suggestions · 46 Solids
Repair    Domain semantics ✓

Round 3   0 Errors · 0 Warnings · 2 Suggestions · 63 Solids
           Ready to generate ✓

The first repair can establish a single domain root and resolve invalid references. The next can distinguish constant objects—such as currencies, countries, and assertion statuses—from mutable business objects such as payments and ledger entries. Later checks can cover relationship integrity, identifiers, required values, temporal fields, and mutation governance.

Each repair is followed by evaluation again. A check mark represents a closed quality gate, not the agent's confidence.

3. Treat Privacy as an Explicit Control Gate

High-compliance domains need separate privacy checks. A privacy evaluation can check supported model-level controls such as masking. The following broader control points are design targets and require independent verification before any compliance claim:

• sensitive-field classification and masking;
• regional data-residency boundaries;
• access and mutation audit requirements;
• retention and deletion policy references;
• signed assertions that avoid moving raw KYB evidence across regions.

The Harness may report that modeled controls for GDPR, CCPA, or PIPL have been checked. This is control readiness evidence, not a legal certification. Deployment configuration, organizational procedures, contracts, jurisdiction-specific interpretation, and continuing operations still require qualified human review.

4. Generate a Typed Contract and an Executable Workspace

Only an accepted model crosses the generation gate. TeaQL can then generate two deliberately separate outputs:

1. A reusable, domain-specific library containing entities, metadata, Q APIs, E APIs, Mutation APIs, Checker/Fix behavior, and a Runtime Module.
2. An application workspace that wires the generated library into an executable service or console.

When generation is remote, the client receives an artifact and places it in the local coding workspace. Retaining a receipt with model, target, generator version, runtime selection, and digest is the desired evidence contract; do not assume those fields or digest verification are already present in every client. This would make “the generated code” a coordinate that can be reproduced, rather than an unidentified ZIP file.

TeaQL currently maintains language-native runtimes for:

Adoption focus	Runtimes
Tier 1	Java, Rust, TypeScript
Tier 2	Go, Swift, .NET, Python

The languages preserve their normal in-process naming and programming conventions while sharing model vocabulary and business semantics.

5. Use Assist as a Continuous, Model-Aware Loop

Generated APIs can be broad. Loading the complete API surface for every entity and field into an agent's context would waste an expensive resource and allow stale guidance to compete with current code.

The agent instead asks for precise guidance when it reaches a task:

Ask for the payment query surface
    → implement a query
Ask for one KYB assertion field
    → add the exact predicate
Ask for the payment mutation contract
    → implement the audited state change

Assist is specific to the current model, entity, field, language, capability, and service version. It is not merely generic documentation. This produces a continuing loop:

inspect task → request Assist → apply exact API → compile or test → request the next Assist

The intended lifecycle is equally important:

Principles stay resident. Capabilities load on demand. Prompts burn after reading. Evidence is retained.

Consume-once Assist content can be isolated to one task while a compact receipt retains its scope, version, digest, and result. Lifecycle metadata is only a declaration unless the Agent or Harness enforces it.

6. Continue Governance at Runtime

Development-time evaluation is only one half of the system. The generated application continues to operate through a TeaQL runtime.

The runtime can enforce or carry:

• execution identity and context;
• query comment and purpose;
• audit reasons for mutations;
• Checker and Fix behavior before persistence;
• loaded, null, and not-loaded state;
• tenant and authorization boundaries;
• mutation-ledger semantics;
• provider-specific execution below a shared business API.

This is the distinction between doing things right during software production and doing the right thing under runtime policy. TeaQL does not choose an organization's business policy. It makes the selected policy explicit, bounded, observable, and auditable.

7. Close the Loop with Executable Evidence

A confident completion message is not evidence. A useful completion record connects the original intent to concrete artifacts and execution results:

• original requirement and modeling assumptions;
• model path, diff, object counts, and important relationships;
• every evaluation round and repaired finding class;
• generator, Assist, runtime, provider, and dependency versions;
• generated library and workspace manifests;
• exact compile, test, and run commands;
• actual results, failures, warnings, and skipped checks;
• artifact and evidence digests;
• remaining human business or legal decisions.

Evidence is version-sensitive. A successful run against an older runtime does not prove the current runtime. A generated example does not prove execution. A test that was skipped must not be presented as green.

8. Compose Federated Applications

The same model-mediated approach extends beyond a single service. A TypeScript application can issue a governed business query to Java and Rust backends through the TeaQL Federated Protocol. Treat this as a bounded integration pattern, not proof that arbitrary cross-service decomposition is already automatic.

TypeScript application
        ↓
TeaQL Federated Protocol
        ↓
Java service · Rust service · other TeaQL runtimes

Federation preserves semantic intent across service and language boundaries. It does not mean exposing unrestricted SQL or hiding authorization inside a transport adapter. Each participating service retains its own runtime context, policy, data boundary, and audit responsibility.

The Responsibility Model

Component	Responsibility
LLM	Interpret intent and propose models or implementation changes.
Skill	Describe the stable operating process and evidence requirements.
Domain model	Define the inspectable business vocabulary and reachable semantic space.
Strong tools	Evaluate, generate, retrieve precise Assist, and enforce action boundaries.
Generated APIs	Provide the typed business contract used by application code.
Runtime	Apply contextual governance while the application executes.
Evidence	Record what was actually checked, with which versions and results.
Humans	Approve intent, policy, exceptions, and residual judgment.

This separation keeps Skills lightweight and moves rules that must always hold into deterministic software.

Explore Further

• Architecture Overview
• Runtime Overview
• Human Review Gate
• Examples and Evidence Index
• Start from an Example
• TeaQL Agent Kit

The interactive TeaQL Harness Visualizer is maintained as an independent component so it can evolve and be reused without coupling its release cycle to this documentation site.