Build Teaql App

Build TeaQL App

Turn a business requirement into a KSML contract and a verified TeaQL application. Never run model evaluation before the first complete KSML model has been written and saved.

Mandatory Workflow Order

Do not reorder these stages:

1. Understand the requirement and choose the model target.
2. Draft and save the first complete KSML model.
3. Only after the model exists, verify the TeaQL client.
4. Evaluate the saved model.
5. Repair from the report and re-evaluate repeatedly.
6. At zero Errors, signal Model Ready and continue without waiting.
7. Generate, implement, compile, test, run, and report.

Prepare the Model Target

1. Read the target repository's nearest AGENTS.md.
2. Capture the original business requirement, model target path, requested language and outputs, and runnable or testable outcome. Supported language families are Java, Rust, Go, Swift, Python, C#/.NET, and TypeScript. A Kotlin/JVM application uses the Java-generated library and Java runtime; do not look for a separate Kotlin generator. Swift uses the swift-lib-core target for a generated Swift package with local SQLite and TFP client support. C++, Dart, Ruby, and other unlisted smaller language ecosystems are not supported.
3. Keep a compact evidence ledger while working. Record commands, evaluation counts, generated guides, assist calls, policy checks, tests, and artifact paths as they occur.

Do not load a full KSML rule catalog before modeling. Use references/golden-example.xml as the grammar example and adapt its structure—not its pet-clinic concepts—to the domain. The golden example exists only to demonstrate KSML syntax. Never carry over its domain names (clinic, pet, appointment, species, microchipped) or its organizational structure into a different business domain.

<!-- BLOCK_ID: phase_modeling -->

Model First

Create and save a complete KSML model before running any TeaQL command. Do not evaluate an absent, empty, or placeholder model target.

If the model is large (e.g., more than 15 objects), you MAY split it into multiple module files using <_include file="module.xml" />, but this is optional. The system supports dynamic output limits so a single-file model will also work.

For a split model, follow the complete multi-file-golden-example. Every included file MUST be a well-formed XML document with exactly one top-level <root> element. Put all module objects inside that <root>. Never write multiple bare top-level objects in an included file. Only the entry file's <root> carries service-level attributes such as name, org, data_service, and _module_key; an included module normally uses plain <root>...</root>.

Incorrect included file:

<customer_account ... />
<sales_order ... />

Correct included file:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <customer_account ... />
  <sales_order ... />
</root>

• CRITICAL: To avoid keyword collisions in any of the seven generated languages, ALWAYS use two-word field names and entity names when there is any risk of conflict (e.g. use bonus_type instead of type, move_order instead of move, leave_type instead of type). Do not use bare single words like type or move as entity or field names.

Apply this minimal contract:

• Make root name the sole model name, in lowercase kebab-case ending with -service.
• Use org="example" when the user does not specify an organization.
• Put objects directly below <root> or within the included module files.
• Give every object _name, _module, and _module_key.
• Use representative literals for ordinary fields so TeaQL can infer types.
• Express a relationship as target_object().
• Do not declare id on business objects.
• Represent reusable finite states as constant objects; only constant objects contain <_value> children.
• In a constant object, every <_value> must explicitly provide every declared data field, including id, name, code, and additional fields such as display_order, color, or progress. Nullable declarations still require a concrete representative value. Do not repeat _... model metadata, version, Fix-managed createTime()/updateTime() fields, or the domain-root relationship injected from context in each <_value>.
• Use generated functions such as createTime() only for their intended semantics.
• IMPORTANT: When writing large split models, create and write the files one by one using sequential tool calls. Do not attempt to output the entire schema for all modules in a single response.

Validation Pitfalls — Avoid on First Attempt

These are the most common first-attempt failures. Avoiding them saves multiple repair rounds:

1. Non-empty attribute values. EVERY attribute MUST have a non-empty representative value. Never write attr="" or attr=" ". Use a realistic example (e.g., email="john@example.com", url="https://example.com/doc.pdf").

2. Language keyword avoidance. Entity and field names must not collide with programming language keywords (Rust: move, type, match, self, ref, mod, box, trait, impl, use, let, fn, async, yield; Java/C#: class, new, import, public, default, return; Go: type, map, range, go, select, interface; Swift: class, struct, protocol, extension, actor, associatedtype, inout, some, any, Self, init, deinit, subscript, operator; Python: class, def, from, import, lambda, yield; Kotlin/JVM application code: object, when, is, fun, val, var; TypeScript: class, interface, function, import, export, typeof; SQL: select, table, transaction). When a natural business concept is a single keyword (e.g., "move"), always use a two-word compound name instead (e.g., move_order, move_task, type_code, match_record).

3. Privacy audit masking. Person-like objects (user, customer, employee, driver, etc.) that hold sensitive fields (password, password_hash, token, magic_link_token, api_key, secret, ssn, id_card, mobile_phone) MUST declare _audit_mask_fields listing those fields. Example: <user _audit_mask_fields="password_hash,magic_link_token" .../>

4. No circular reference chains. If A references B, B references C, and C references A, the parser may fail at depth limit. Keep reference chains short and acyclic.

5. Audit log user field. Logging/audit objects (audit_log, change_log, etc.) MUST include a recognizable user/operator field (e.g., operator="user()", actor="user()").

6. No isolated entities (Disconnected Graphs). To avoid KSML-DOMAIN-ROOT-002, ensure that ALL entities are connected via relationships (references) to the main graph. Do not leave any entity as an isolated island. Every object should either reference another object or be referenced by another object in the domain model.

7. No XML special characters in attribute values. Never use &, <, >, " directly in attribute values. Use and instead of & (e.g., _module="Operations and Logistics" not _module="Operations & Logistics").

8. Complete constant value records. Every <_value> must provide every declared constant data field. A nullable type declaration does not permit a value record to omit that business field. Version, Fix-managed createTime()/updateTime() fields, and the domain-root relationship are runtime managed and omitted from each row.

   <school_type platform="platform()" id="id()" name="string()"
                code="string()" display_order="number()" color="string()?"
                _constant="true" _identifier="code">
     <_value id="1001" name="Primary" code="PRIMARY"
             display_order="1" color="blue"/>
     <_value id="1002" name="Secondary" code="SECONDARY"
             display_order="2" color="green"/>
   </school_type>

When you finish the model generation phase and evaluation passes with zero errors, output <phase-complete>model_generation</phase-complete>.

Evaluate and Repair the Saved Model

Now—and only now—load references/toolchains.md. Verify the installed client against the exact version required by the target repository or that reference. Stop and report a mismatch.

Submit the complete model target to the repository's Generation Service evaluation command. For Rust, every model-derived operation must include:

cargo teaql --input <model-file-or-directory> evaluate

IMPORTANT: If your model is split into multiple files in a directory (e.g., models/), you MUST pass the directory path (e.g., --input models/), NOT the main entry file (main.xml). Passing only the main file will cause the evaluator to fail with missing included files.

Repair from the Markdown evaluation report:

1. Fix all Errors, largest repeated pattern first.
2. Preserve Solids and already-correct model sections.
3. Re-evaluate after each repair round.
4. Resolve Warnings using the business requirement.
5. Treat Suggestions as optional.
6. Follow the report's concrete repair guidance rather than guessing or memorizing a separate rule catalog.
7. IMPORTANT: When dealing with extremely long evaluation logs (e.g., thousands of lines), DO NOT use paginated reading commands (like sed -n '1,300p') in an endless loop to read the entire file. Use targeted grep (e.g., grep -A 15 -B 5 "Error" or grep -A 10 -B 10 "error:") or read only the head/tail to quickly isolate and fix issues without wasting context.

Do not generate from a model with errors.

Repair Budget

Run at most 5 evaluation–repair rounds by default. If errors remain after 5 rounds, stop and present the current evaluation report to the user with a summary of what was fixed and what still fails. Ask the user to provide additional guidance or model corrections before continuing. Do not loop indefinitely.

On small-context models, keep the zero-error evaluation gate. Read the summary and only the reported error locations needed for the current repair round; do not stream the complete report into context. If the remaining errors cannot be resolved within the repair or context budget, stop with the current report. Never proceed to generation with evaluation errors.