Skip to main content

Human Review Gate

TeaQL reduces the amount of persistence code that humans need to review, but it does not remove the need for human judgment. The review gate should focus on model intent, authorization boundaries, generated API usage, and evidence from build or generation commands.

What Humans Must Review​

Review the model first:

  • New entities and relationships match the business language.
  • Ownership and tenancy boundaries are explicit.
  • Sensitive fields are modeled intentionally.
  • Nested references do not create unnecessary traversal depth.

Review generated API usage:

  • The code uses generated Q APIs instead of raw SQL for business data access.
  • Method names match generated source.
  • Queries include comment and purpose before execution.
  • Saves and updates include audit metadata.
  • Relationship loading is explicit enough for the screen or workflow.

Review runtime boundaries:

  • Authorization and tenancy flow through UserContext or runtime policy.
  • Provider-level code does not leak into business services.
  • Audit trail and logging behavior remain enabled where required.

What Machines Should Check​

Automated checks should catch repeatable failures:

  • Compile errors after generation.
  • Missing comment or purpose before query execution.
  • Missing audit_as / auditAs before save or update.
  • Invalid KSML.
  • Depth limit violations.
  • Markdown error reports from eval or generation commands.

Evidence to Attach​

For a meaningful review, attach:

  • The model diff.
  • The application code diff.
  • The generation or eval command output.
  • Any Markdown error report.
  • The focused test or build command used to verify the change.

Review Outcome​

A TeaQL change is ready when the model is understandable, generated APIs compile, runtime policy is preserved, and the code expresses business intent without requiring reviewers to reconstruct SQL or storage joins by hand.