Coding Agents and Native Code Validation
Coding agents work best when each change follows the same sequence: retrieve the relevant contract, adapt a verified example, check the patch, and execute a bounded test in the correct context. Use the Kilo Code setup guide and copyable project instructions to configure this workflow.
Choose the right evidence
| Question | Source in this repository |
|---|---|
| Is an iXML command or attribute supported? | ref/ixmldoc.xml, including prose, children, and result bindings |
| Does a Zymba method exist and what does it accept? | ref/zymbaref.json and ref/zymbadoc.md |
| Is a database identifier or relationship real? | ref/dbref.json, ref/simpledb.sql, and ref/views.txt |
| What does an API operation accept? | The corresponding file in ref/openapi/ |
| What will an SDK command do? | The corresponding file in ref/sdk/ and installed SDK help |
| Has this example run successfully? | Dated entries in LEARN.md, including later failures |
| How does this application pass inputs? | The calling service/resource/weblet, manifest, and application lessons |
Search for the exact symbol, then read its complete reference entry. Looking up only the command name misses defaults, result bindings, and context restrictions. Treat a conflict between the reference and a runtime observation as a compatibility issue to investigate. Do not change read-only reference material to make a generated example appear valid.
The Zymba guide tree is deferred draft material. Use its official reference and execution evidence when working on native Zymba; do not infer support from PHP or JavaScript.
Format XML without changing behavior
Keep existing indentation and envelope conventions. For new examples, use two spaces per nesting level, double-quoted attributes, and one logical statement per line. Put long attribute lists on separate indented lines. Keep short text values on one line and use /> consistently for empty elements. These are editing conventions, not language requirements.
This is a readable form of the comparison fragment recorded as successful on 6 February 2026:
<if value1="3" value2="3">
<output>This is true</output>
</if>
Its expected result is This is true. The default comparison is equality. There is no condition attribute.
For XML syntax inside attribute values, escape < as <, > as >, & as &, and a double quote as ". Preserve intentional entity references instead of double-escaping them. A comparison such as func="<" is the documented representation of less-than. Raw < inside an attribute failed in the execution log.
Preserve text nodes, CDATA, and embedded HTML, JSON, or SQL. A formatter must not collapse significant spaces, move a literal across a command boundary, or rewrite an established namespace/envelope merely to satisfy a generic XML tool. Native snippets can contain multiple statements and prefixed command names; a generic namespace-aware parser may reject a fragment that the ZeyOS runtime accepts. Document-specific entities such as &n; also need the appropriate parser context.
Preserve result propagation
An element can receive a result from a child statement. Literal text alongside embedded code is not ordinary string concatenation. The reference explains that these literal values are discarded, and this exact fragment returned 27 in LEARN.md:
<output><set>$(15 + (7.5 * 2 - 3))</set>471</output>
Do not reformat or rewrite that expression assuming it produces 27471. When building text, use a documented string operation or substitution into a separate text-only statement:
<set var="name">iXML</set>
<output>Hello $name</output>
This exact fragment returned Hello iXML. $ substitutes a value; it is not part of the declared variable name. <set var="$name"> is invalid.
Make types explicit
set content defaults to a string. The following recorded example returns int after an explicit cast:
<set var="test">42</set>
<cast var="test" type="int" />
<typeof var="test" var_result="t" />
<output>$t</output>
The formatted examples above reuse historically executed fragments; they are not new execution results for the current instance. Keep standalone test fragments distinct from complete application files, which may require an envelope and an entry-point context.
Validate parameters and structure
For every changed command, inspect:
- The exact command name and its documented attributes, input types, defaults, and allowed values.
- Valid parents, children, occurrence constraints, and whether the content is text or executable iXML.
- Result bindings and whether the result propagates to its parent.
- Conditional requirements and restrictions described in prose.
- The actual input contract of any called function, include, service, or hook.
The reference's attribute list is not a complete required-parameter schema. An absent default does not establish that the attribute is mandatory. Likewise, an empty OpenAPI required list does not prove that an API accepts an empty payload. Combine metadata with prose, application contracts, database constraints, and runtime evidence.
For example, this function and call were executed successfully in the log:
<function var="fullName">
<set var="return">$firstname $lastname</set>
</function>
<call func="fullName" var="name">
<param name="firstname">Ada</param>
<param name="lastname">Lovelace</param>
</call>
<output>$name</output>
Expected output: Ada Lovelace. An agent checking required application inputs must inspect how firstname and lastname are used and what the caller promises. XML well-formedness alone cannot detect a missing business input. Exercise omitted, empty, malformed, and valid input cases where the application's behavior depends on them.
Validate database requests
Write a short identifier map before writing the query. For each table or view, selected field, condition, sort expression, and join, record its exact name and source. Check column case, types, defaults, identity/generated flags, foreign keys, and enums. A CLI alias is not a database table name, and a UI label is not a column name.
For this recorded read example, the map is users → table; u → local alias; u.ID → the ID column on users:
<db:select var_result="users" type="assoc" limit="1">
<db:fields>
<db:field>u.ID</db:field>
</db:fields>
<db:table alias="u">users</db:table>
<db:orderby>
<db:orderfield>u.ID</db:orderfield>
</db:orderby>
</db:select>
<output>$users[0].ID</output>
This returned 1 in the historical sandbox. Another instance can return a different ID or no row. The example assumes a visible user exists; application code must handle an empty result before using the first row.
db:select uses var for the generated SQL string and var_result for retrieved rows. type="assoc" requests rows with field names as keys. Capturing the SQL text is not a database validation pass, and this command is documented as generating and executing the query; do not advertise it as a dry-run facility.
For joins, follow every foreign key to its destination. accounts.contact references contacts.ID; that relationship does not imply any proposed field on contacts exists. Check each terminal field and expected cardinality. For native SQL, use documented query construction/preparation and distinguish escaped values from allowlisted identifiers. Never invent placeholder syntax or interpolate untrusted data directly.
Check business meaning after checking identifiers: a one-to-many join can duplicate totals, a nullable relationship can remove rows, and a page limit can make a count incomplete. Validate the expected result shape, null handling, stable ordering, and empty-result behavior.
External requests use a different validator
The zeyos CLI's describe and --dry-run, and client.schema.validate(), catch common API mistakes before a request. Client/CLI 1.0.0 and later check complete documented FK paths and custom keys supplied through customFields (JavaScript) or an instance-bound ZEYOS_CUSTOM_FIELDS_FILE snapshot (CLI/MCP). Missing definitions fail explicitly. Confirm snapshot provenance and refresh after configuration changes; offline discovery does not query the tenant. Older releases accepted joined suffixes and custom fields unchecked, so use the matching client build. These checks do not validate native SQL or compile scripts. The curated required-create supplement covers account currency; check other required inputs against the endpoint and runtime. See the API validation workflow.
Apply the same discipline to Zymba
When local references are unavailable, use the authoritative symbol index and namespace index. Entries retain exact declarations, a source hash, and a JSON pointer into the official reference mirror. Fetch only the relevant namespace, such as Array, or the reference working set. Preserve duplicate declarations and static/instance distinctions. Read raw parameter/default/return metadata and annotations; a generated signature does not establish runtime correctness or a complete required-input contract. This reference index does not promote the deferred Zymba guide drafts.
Before calling a method, verify the class, receiver, argument order, optional/defaulted and nullable parameters, return value, and mutation behavior. A nullable parameter and an optional parameter are different concepts; read the default and signature information rather than assuming a nullable argument can be omitted.
The execution log provides useful regression cases:
| Mistake | Reference-backed behavior |
|---|---|
Concatenating strings with + | Use .; + performs numeric addition |
Calling @String.length | Use count or @String.countChars |
Calling @String.joinValues | Use @Array.joinValues with its documented arguments |
Checking is array | Arrays are objects; use the documented type system |
| Using PHP magic constants | __FILE__, __LINE__, and __FUNCTION__ failed in the recorded runtime |
Do not replace those checks with a generic PHP/JavaScript linter. Validate native syntax and behavior through ZeyOS. Preserve the application's conventions for service parameters and object methods.
Report validation precisely
| Stage | What it establishes | What remains |
|---|---|---|
| Reference review | Names, signatures, result bindings, and documented constraints | Runtime/version differences and application behavior |
| Local structure/schema checks | Errors within the checker's explicit coverage | Dynamic values, missing metadata, permissions, business rules |
| Sandbox execution | Observed behavior for the supplied input and runtime | Other inputs and invocation contexts |
| Entry-point integration test | Behavior through the intended hook, form, service, or HTTP request | Production-specific data and operational conditions |
zeysdk run requires a linked application and network access. Confirm the sandbox and use the existing private authentication mechanism before executing. Start with the minimal historically verified fragment:
zeysdk run --ixml '<output>hello</output>'
Expected output: hello. Run from the application's linked directory; sandbox/guideapp is this guide's historical local setup, not a directory guaranteed to exist in another project. An inline REST example in the log produced HTTP 404 because the invocation did not simulate the inbound route. A parser success is not proof that the intended route ran.
Keep new findings in the application's designated validation log with date, code revision, reference version/hash, input, expected output, actual output, and invocation context. Redact private data. Updating this guide's pinned LEARN.md requires the separate release workflow.
When execution is unavailable, finish the reference and static review and state the exact sandbox test still needed. Never label unexecuted code as runtime-validated.
Improve automation incrementally
A useful future checker can index iXML command/child contracts and Zymba method signatures from the references, resolve static database identifiers, and report source locations for each diagnostic. Dynamic names and incomplete metadata must yield a request for runtime evidence, not a false pass. This is a proposed extension, not an existing compiler supplied by the guide.
Start a regression collection with the failures above. Enable complete API relationship-path validation and supply reviewed tenant custom-field metadata before expanding unattended writes. Native SQL still requires reference and runtime checks. Preserve reference provenance and test formatting changes for result equivalence. Use restricted tools and credentials to enforce operation scope; instructions provide working guidance, not isolation from a production system.