Skip to main content

Regenerate and Review

Regeneration is the normal TeaQL development loop. The model is the source of truth; generated Java or Rust source is an output.

Before Changing the Model​

  1. Make sure the current generated project builds or passes its relevant tests.
  2. Keep the working tree focused enough that generated changes can be reviewed.
  3. Find the entity source generated from the model element you plan to change.
  4. Record the current generated method names instead of guessing what the next generation will create.

Make One Small Change​

For a first regeneration exercise, add or rename one non-relational field. Avoid changing ownership, tenancy, roots, or several relationships at once. Those changes have wider schema and API consequences.

Follow the KSML rules in the modeling guide and leave no empty attributes.

Evaluate Before Generating​

Use the client for the target stack:

cargo teaql evaluate --input model/main.xml

or, with TeaQL Maven plugin 1.1.0:

mvn io.teaql:teaql-maven-plugin:1.1.0:eval -Dinput=model

Read any Markdown validation report in the console, correct the source model, and evaluate again before generation.

Generate​

Use the generation command supported by the installed client:

cargo teaql services
cargo teaql rust-lib-core \
  --input model/main.xml \
  --output generated/rust-lib-core

For Maven-based generation, inspect the verified plugin goals first:

mvn io.teaql:teaql-maven-plugin:1.1.0:list-services

Then pass the selected dynamic target to generate:

mvn io.teaql:teaql-maven-plugin:1.1.0:generate \
  -Dservice=java-lib-core \
  -Dinput=model

Do not assume that an older project's target names, flags, or output paths apply to the current client.

Review the Diff​

Review generated changes by responsibility:

AreaWhat to verify
ModelThe intended field, type, relation, or annotation is the only semantic change.
EntityThe generated property and exact update/access methods match the model.
Request APINew filters, selections, ordering, or relation methods are expected.
Metadata/schemaField type, nullability, and relation metadata are correct.
Handwritten codeCompile failures are resolved by using the new generated contract, not by patching generated source.
DependenciesGenerator-emitted runtime versions remain compatible.

Large unrelated diffs are a reason to stop and identify a generator version, template, configuration, or formatting change before proceeding.

Verified Rust Regeneration Example​

The 2026-07-13 Golden Path changed one user_info field set with email="philip@example.com" and advanced the model version from 1.0.0 to 1.0.1. Evaluation produced no errors and correctly suggested adding _audit_mask_fields="email". After that source-model annotation was added, evaluation reported zero suggestions and generation was repeated.

The reviewed generated diff contained:

  • crate version 1.0.1;
  • the email entity field and exact update_email method;
  • get_email expression support;
  • generated selection, filtering, grouping, and ordering methods for email;
  • audit_mask_fields = "email" on the generated entity metadata;
  • no TeaQL runtime or provider version change.

The regenerated crate then passed cargo test --offline. This is an evidence example, not permission to assume method names for another field or generator version; inspect that run's generated entity and request sources.

Java status for the same change​

TeaQL Maven plugin 1.1.0 also evaluated and regenerated the version 1.0.1 model with zero errors or suggestions. The reviewed Java diff added the exact updateEmail method, checker, expression, selection, filtering, grouping, ordering, and audit_mask_fields entity metadata expected from the model.

The Java workspace could not complete its build because the current template emits the nonexistent teaql-data-service-sqlite artifactId and entity methods named internalSet/internalGet, while teaql-core 1.525-RELEASE publishes teaql-sqlite and exposes __internalSet/__internalGet. The diff is useful regeneration evidence, but it must be rebuilt after the upstream template is fixed before Java runtime behavior can be claimed.

Verify the Result​

  1. Build or test the generated workspace.
  2. Read the generated entity source for exact method names.
  3. Run the smallest query or mutation affected by the change.
  4. Confirm queries declare comment and purpose before execution.
  5. Confirm mutations declare audit intent before save or update.
  6. Preserve the model change and regenerated output according to the project's source-control policy.

Never Fix Generation by Patching Output​

If generation is wrong, change one of these inputs instead:

  • the KSML model;
  • generator configuration;
  • the generator or template version;
  • a documented handwritten extension point.

Manual generated-source edits disappear on the next run and hide the real problem from both reviewers and AI coding agents.

Next Steps​