typeql-preflight

name	typeql-preflight
description	Pre-flight checklist for TypeDB 3 schema edits in the typedb_tactics package. Invoke before writing or editing any .tql schema file to catch known error patterns before running Docker tests.
user-invocable	false

Before editing or writing a TypeQL schema file, run through this checklist and flag any violations:

Syntax constraints (will cause parse/commit errors)

1. No rule blocks — TypeDB 3 removed rules. Use fun with with fun name($arg: Type) -> ReturnType: syntax. Violation: [TSV7]
2. Relation variable syntax — use $r isa T, links (role: $x) — NOT $r (role: $x) isa T. The latter triggers [REP1] even inside fun match bodies.
3. No dual Object+ThingType declaration — in a single INSERT block, you cannot create a named relation variable $r and also use it as a role player in the same block. Make intermediate relations anonymous. Violation: [REP1]
4. No variable reuse across pipeline stages for different types — if $e was bound as propositional_expression in stage 1, do not reuse $e for not_expression in stage 2. Use unique names per stage. Violation: [INF11]
5. Return syntax — return max($m); and return min($m); require parentheses. return max $m; is invalid.
6. Boolean returns — return true; is invalid. Use let $r = true; return first $r;
7. -> boolean not -> bool — use -> boolean in function signatures. bool causes [INF2].

Function body constraints

8. Cross-OR-branch function call results — cannot bind a function-call result directly to a variable that appears across OR branches. Use double-let: let $tmp = func(...); let $out = $tmp;. Violation: [CEX18]
9. OR branch isa type guards — only include isa branches for types that actually play the role being matched in that fun. If a type cannot play the role, TypeDB raises [FIN0]/[QUA1] at schema commit.
10. No mutual recursion between fun bodies — the function call graph must be a DAG. Violation: [FUN9]
11. links can be hoisted before { } or { } blocks — valid and faster. isa constraints before the outer OR block cause a parse error — keep those inside branches.

Performance (apply when writing new functions)

12. OR branch ordering — for return first functions, put the branch matching the MOST inputs first. For batch/all-rules queries this is the dominant performance lever (confirmed −37% gain in this codebase).
13. OR branch ordering does NOT help return min/return max — TypeDB evaluates all branches for aggregators; early-exit does not apply.
14. Keep OR branches inline — do not split into separate functions for dispatch. Cross-function overhead is 147× in TypeDB 3 (confirmed).
15. One match stage — the optimizer only reorders within a single stage. Splitting into two stages disables cross-constraint optimization.

Before committing

• Check src/typedb_tactics/agent-docs/schema-guide.md for module intent before adding new types.
• Run tests in Docker: scripts/run-tests-docker.sh
• If adding a new fun, ensure every OR branch has at least one test case that hits it.
• Use text2typeql examples as a reference: python3 scripts/find-text2typeql-examples.py "query intent" --top-k 5